---
title: 版本與淘汰政策
description: Recur REST API 如何版本化，以及淘汰時會用哪些 HTTP header
---

# 版本與淘汰政策

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：

| 環境 | 上限 |
|------|------|
| Sandbox（`sk_test_` / `pk_test_`） | 每分鐘 120 次 |
| Production（`sk_live_` / `pk_live_`） | 每分鐘 600 次 |

超過時 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 認證](/getting-started/authentication)
- [冪等性](/api-reference/idempotency)
- [錯誤碼](/api-reference/error-codes)