開放平台 API 錯誤與限制

開放平台 API 的錯誤回應主體與模型介面不同：結果由 HTTP 狀態碼表達，JSON 主體固定包含 success，失敗時另帶機器可讀的 code。

回應格式

成功時回傳 HTTP 200：

{
  "success": true,
  "message": "",
  "data": {}
}

失敗時使用真實的 HTTP 狀態碼，回應主體帶有機器可讀的 code：

{
  "success": false,
  "message": "管理金鑰無效",
  "code": "invalid_token"
}

message 是在地化的提示文案，可能隨版本調整，程式判斷請使用 HTTP 狀態碼和 code。

錯誤碼

HTTP	code	情境
400	invalid_request	參數不合法，如金額越界、建立時名稱為空或過長、status 取值不是 1 / 2、啟用的 Key 仍過期或用盡、過期時間不合法、分頁或時間範圍不合法、query 含未編碼的 ;
401	invalid_token	缺少 Authorization 標頭、格式錯誤、金鑰不存在或已刪除
401	token_expired	管理金鑰已過期
401	token_revoked	管理金鑰已撤銷（僅存量金鑰；新建金鑰只能刪除）
403	user_disabled	管理金鑰所屬使用者已被停用
403	insufficient_scope	管理金鑰缺少本介面所需的權限
404	not_found	API Key 不存在或不屬於你（兩者不區分）；或 /api/open/v1 下不存在的路徑
405	method_not_allowed	路徑存在，但不支援該 HTTP 方法
429	rate_limited	超過每個管理金鑰的頻率限制
500	internal_error	伺服器錯誤，不回傳內部細節

/api/open/v1 下未知路徑回傳 404，方法寫錯回傳 405，兩者都使用上面的統一錯誤體；code 可用於區分「換個方法重試」還是「路徑或參數寫錯了」。

頻率限制

範圍	限制	適用介面	超限回應
每個管理金鑰	120 次/分鐘	全部開放平台 API	429，code 為 rate_limited
每個使用者	30 次/分鐘（預設）	帳戶日誌、匯出日誌、用量統計、按模型統計、按 Key 統計	429，回應主體可能為空
每個用戶端 IP	180 次/180 秒（預設）	全部 /api 介面共用	429
每個用戶端 IP	100 次/20 分鐘（預設）	敏感介面，如 取得完整 API Key	429，回應主體可能為空

請依 HTTP 狀態碼處理限流。遇到 429 時請降低頻率並稍後重試。

模型介面使用另一套錯誤結構和限流規則，見常見錯誤。