错误与状态码
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,对账不受影响。