API 錯誤
判斷 API 錯誤:何時修改請求、何時重試,以及如何重試付款或群發而不建立重複操作。
本頁內容
請求失敗時,先看 HTTP 狀態碼:401 通常代表存取問題,429 代表請求太頻繁。回應的 error 欄位說明原因;成功回應直接包含資料,沒有共同的外層包裝。
錯誤格式
伺服器以只有 error 欄位的 JSON 物件回報錯誤:
{"error":"reaction not found"}
應先依 HTTP 狀態碼判斷處理方法,error 文字可用於記錄和畫面提示。
狀態碼
| HTTP | 含義 |
|---|---|
200 OK | 成功,內容為資料 |
201 Created | 已建立資源,部分 POST 端點使用 |
204 No Content | 成功但無內容,部分刪除操作使用 |
400 Bad Request | 請求內容或參數有誤 |
401 Unauthorized | 權杖缺失、無效或過期,或路徑不接受 PAT |
402 Payment Required | 方案或配額不足,例如媒體庫需要付費功能 |
403 Forbidden | scope 不足,或缺少帳號空間權限(missing cabinet right);見權杖所屬空間 |
404 Not Found | 資源不存在或不屬於你 |
409 Conflict | 狀態衝突;帶 Idempotency-Key 時也可能表示同一操作正在執行 |
413 Payload Too Large | 內容超過限制;帶 Idempotency-Key 的操作上限另為 64 KiB |
422 Unprocessable Entity | JSON 語法有效但業務檢查失敗;同一冪等鍵搭配不同內容時也會回傳 |
429 Too Many Requests | 超過請求頻率限制 |
500 Internal Server Error | 伺服器內部錯誤,稍後可重試 |
大小及頻率限制詳見限制與大小。
如何處理
2xx 表示成功。遇到 401/403,請檢查權杖、scope 和帳號空間權限。遇到 429 或 5xx,可用逐漸增加的等待時間重試(指數退避)。其他 4xx 通常應先修正請求。
有一個例外:帶 Idempotency-Key 的請求回傳 409,可能表示相同操作仍在執行,並非請求有誤。此時不要放棄付款或群發,應依回應的 Retry-After 等待,並用同一個鍵重試。
重試付款與群發:Idempotency-Key
鍵須為標準 UUID,使用小寫與連字號,例如 9b1f0d4c-2f6a-4a5f-9a3f-1f2f3a4b5c6d。格式不符會回傳 400。
適用路徑
在以下可能花費金錢或觸發大規模發送的操作,標頭可省略,但設定後會生效:
POST /api/billing/topup:儲值。POST /api/billing/subscribe:訂閱方案。POST /api/bots/{botID}/reactions/{reactionID}/broadcast:啟動群發。
以下兩種客服發送操作則必須提供該標頭,否則回傳 400:
POST /api/bots/{botID}/users/{userID}/dialog/messages。POST /api/bots/{botID}/support/dialogs/{subscriberID}/templates。
其他路徑會忽略此標頭,不能把它當成通用的防重複保護。
伺服器如何回應
- 同鍵、同內容,操作已完成:回放第一次的狀態碼及內容,另有
Idempotent-Replay: true;操作只執行一次,記錄保留一週。 - 同鍵,操作仍在執行:回傳
409和Retry-After,等待後仍用原鍵重試;換鍵可能建立第二筆操作。 - 同鍵、不同內容:回傳
422,請為真正不同的操作使用新鍵。 - 內容超過 64 KiB:回傳
413,應檢查客戶端請求。
5xx、408、425、429 的回應不會記入冪等回放,因為它們代表操作未成功完成;以同鍵重試仍可再次執行。若記錄這些錯誤,同一鍵在一週內都只會回放失敗結果。
實際操作
- 第一次請求之前產生 UUID,並與工作記錄一起保存。
- 將此鍵放入
Idempotency-Key標頭傳送。 - 斷線、逾時、
5xx或429時,以相同鍵重試。 - 收到
409時,等待Retry-After再用同鍵重試。 - 只有真正的新操作才使用新鍵。
每次重試都重新產生鍵,是最常見的錯誤:看似有設定標頭,實際上每次對伺服器都是新的操作。
AI 與流程設定錯誤
Managed AI 可能回傳 not_available(功能未啟用)、not_entitled(沒有權限)、budget_exceeded(預算耗盡)、rate_limited(請求太頻繁)、provider_unavailable(模型服務不可用),或 schema_validation_failed(回覆未通過格式檢查)。只有回應允許重試的錯誤才應以相同 Idempotency-Key 重試。429 以外的 4xx 或格式驗證失敗應修正請求;改用另一家模型供應商不能解決格式錯誤。
Copilot 回傳 stale_base 時,代表建議是按舊版反應建立的,請根據目前結構重建。其他請求已修改分析規則時,更新可能回傳 409。分析重新計算與執行重播是有範圍的任務,啟動新任務前應先查看既有任務狀態。Meta 連接檢查會回傳可用於找出問題的原因碼,但錯誤不會包含 Meta 回應內容或存取權杖。