18. 錯誤碼與錯誤處理#
介面出錯時回傳 OpenAI 相容的錯誤結構（/v1/messages 端點回傳 Anthropic 格式的錯誤結構）：
JSON
{
"error": {
"message": "错误描述",
"type": "invalid_request_error",
"code": 400
}
}
常見狀態碼#
| 狀態碼 | 含義 | 排解建議 |
|---|---|---|
400 | 請求參數缺失或不合法 | 檢查 model、messages、input 等必填欄位；/v1/messages 勿傳 tools / 多模態 |
401 | 缺少或無效的 API Key | 確認 Authorization: Bearer sk-... 正確，Key 未過期 / 未被吊銷 |
402 | 配額用盡或餘額不足 | 在控制台儲值或調整 Key 配額 |
403 | 來源 IP 不在白名單 | 檢查 Key 的 IP 白名單設定 |
404 | 模型不存在或無權存取 / 任務不存在 | 用 GET /v1/models 確認可用模型；確認路徑為單一 /v1 |
429 | 觸發速率限制 | 降低併發，指數退避後重試 |
500 | 閘道內部錯誤 | 稍後重試；持續出現請聯絡支援 |
502 | 上游供應商回傳異常 | 稍後重試或更換模型 |
503 | 無可用通道 | 該模型暫無可用上游，稍後重試或聯絡支援 |
錯誤處理建議#
- 對
429、5xx做自動重試（指數退避 + 最大重試次數）。 - 對
400、401、403等用戶端錯誤不要重試，應修正請求。 - 記錄回應中的
X-Request-Id（如有），便於排障時提供給支援團隊。