版本與淘汰政策

Recur 公開 REST API 的 Base URL 是：

https://api.recur.tw/v1

目前只有 v1。路徑裡的 v1 就是穩定合約。沒有未公告的第二個公開版本。

相容變更（不升版）

下列變更會直接出現在 v1，不另外開版本：

• 新增欄位、可選參數、新 endpoint
• 新增 error code（既有 code 語意不變）
• 新增 response header

客戶端必須忽略不認識的 JSON 欄位。

破壞性變更

若必須移除或改變既有欄位、路徑或認證方式：

1. 至少 90 天 前在文件標明淘汰，並在受影響的 response 加上 Deprecation: true 與 Sunset（HTTP-date）。
2. Link 會指向替代文件，例如本頁或後繼版本。
3. 到期後才從 v1 移除。不會在沒有 Sunset 的情況下突然切斷。

目前 沒有 進行中的淘汰。v1 沒有 Sunset 中的欄位。

Rate limit

認證後依 API key：

超過時 HTTP 429，並帶 Retry-After。api.recur.tw 目前由 Next.js API routes（apps/web）提供：middleware OPTIONS 與 route 401/200 都帶這些 header。Hono（apps/api）尚未切成正式入口，/v1 全域 middleware 回同一組 header（含 CORS OPTIONS）。

所有 REST 回應（含 401 與 OPTIONS）都會帶：

• RateLimit-Limit
• RateLimit-Remaining
• RateLimit-Reset
• RateLimit（limit=…, remaining=…, reset=…）
• 相容用的 X-RateLimit-*

相關

• API 認證
• 冪等性
• 錯誤碼