錯誤與狀態碼
EasyJev 返回的全部狀態碼:帶 request_id 的統一錯誤 JSON 結構、完整錯誤碼表(400/401/402/403/404/413/422/429/502)、重試建議與上游透傳語義。
統一錯誤結構
閘道自身產生的失敗(鑑權、額度、限流、上游耗盡……)在 /v1/* 路徑上都返回這個 JSON 錯誤體。例外是上游校驗錯誤——原樣透傳(見 systemone 頁)。
{
"error": {
"message": "Balance is not enough to make this call",
"type": "insufficient_quota",
"code": "insufficient_quota"
},
"request_id": "8f14e45fceea167a5a36dedd4bea2543"
}狀態碼總表
| HTTP | type | code | 含義 / 處理 |
|---|---|---|---|
| 400 | invalid_request_error | 上游透傳 | 上游拒絕請求體。按上游訊息排查;不計費。 |
| 401 | authentication_error | invalid_api_key | Bearer 金鑰缺失/錯誤。檢查 sk- 值;被停用的 key 也走這裡。 |
| 402 | insufficient_quota | insufficient_quota | 餘額為零/負。儲值後重試。 |
| 403 | authentication_error | account_suspended / key_disabled | 帳號或金鑰被停用——聯絡支援。 |
| 404 | invalid_request_error | model_not_found | 模型不在售賣清單(或拼寫錯誤)。用 GET /v1/models 查有效名。 |
| 413 | invalid_request_error | payload_too_large / media_too_large | 請求超大小限制——縮小請求體或拆分資產。 |
| 422 | invalid_request_error | bad_request(閘道)/ 上游透傳 | 缺 model/state/questions,或上游 schema 拒絕。 |
| 429 | rate_limit_error | rate_limit_exceeded | 按 key 的 RPM/TPM 觸頂。退避重試(限流視窗一分鐘內滾動重置)。 |
| 502 | api_error | upstream_failed | 故障轉移後全部「渠道+key」嘗試失敗。可退避重試;持續出現請攜 request_id 聯絡支援。 |
重試建議
RETRY
可安全重試:429(先退避——滑動視窗一分鐘內釋放容量)與 502(故障轉移已耗盡,上游瞬時故障常見)。不要盲目重試 400/401/402/403/404/413/422——必須先修正請求本身。每次重試都帶新的 request_id,對帳不受影響。