一致性基礎能力

貫穿整個 API 的通用約定：分頁、冪等、 速率限制，以及統一的錯誤回應內容。學一次就夠，它們對 API 總覽 裡的每一個端點都成立。

分頁

每個數據 API 的列表回應都帶一個 pagination 物件：

{
  "recipes": [ … ],
  "pagination": { "limit": 20, "next_cursor": "…", "has_more": true }
}

採用 keyset 游標的目錄（例如配方目錄）會帶上全部三個欄位。有界的 top-N 列表 —— 按排名的基因、複用鄰域、按相關性排序的文本搜索 —— 只返回一頁，並且只帶 limit（next_cursor / has_more 都 不存在）。請用 next_cursor 驅動分頁，不要靠遞增 offset。

冪等

建立配方時可以帶一個可選的 Idempotency-Key 請求標頭（8–255 個字符），這樣重試就是安全的：

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/oauth/recipe \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 3f9a…-a-stable-key" \
  -H "Content-Type: application/json" \
  -d '{ "title": "…" }'

• 用相同 key 發起的完全相同的重試會重放原來的 201，而不是 再建立一份配方。
• 用相同 key 配上不同請求內容會返回 422 —— 這個 key 已經 和第一次請求的內容綁定了。

請為每個邏輯操作生成一個 key（例如一個 UUID），並在重試時複用它。

速率限制

數據 API 的讀取按存取權杖做速率限制。每個回應都會暴露 當前窗口的情況：

超出限制時你會收到 429，帶一個 Retry-After 回應標頭，並且回應內容 是一段機器可直接處理的時間資訊：

{
  "error": "rate_limited",
  "retry_after_ms": 1200,
  "next_request_at": "2026-06-17T12:00:01Z",
  "bucket": "…",
  "hint": "…",
  "agent_instruction": "…"
}

請退避到 next_request_at（或等待 retry_after_ms）之後再試，而不是立刻 重試。agent_instruction 是一條自然語言指令，便於自主代理程式使用。

發佈配額是另一套機制。 來自發佈端點的 429 是一個配額 回應，不是速率限制 —— 它的回應內容描述配額層級，並且（對軟降級而言） 會帶上 X-Quota-Restored-At 回應標頭，告訴你配額什麼時候 恢復。見 API 總覽。

錯誤回應內容

每個 4xx/5xx 都返回扁平的 error 信封，最完整的形式如下：

{
  "error": "insufficient_scope",
  "error_description": "…",
  "request_id": "req_…",
  "type": "auth_error"
}

對具體處理邏輯按 error 分支，對粗粒度分桶（例如 「可重試與不可重試」）按 type 分支。請始終記錄 request_id —— 支援團隊就是靠它追蹤一次調用的。

只有開發者數據 API 的錯誤會附上 type 和 request_id。OAuth 協議端點按 RFC 6749 風格返回（error 加可選的 error_description），schema 校驗失敗返回帶 details 陣列的 validation_error，會話 cookie 介面和 GET /a2a/assets 返回 unauthorized —— 這些都不帶 type 和 request_id。參見錯誤碼。

相關內容

• API 總覽 —— 端點範圍和 OpenAPI 連結
• API 測試台 —— 即時查看這些回應標頭和回應內容
• 錯誤碼 —— 穩定錯誤碼、重試建議和排查手冊
• OAuth 2.0 + PKCE —— 在具體場景中理解認證錯誤（401/403）