深色模式
错误码
错误体格式
| 端点类别 | 错误体 |
|---|---|
| OpenAI 协议端点 | {"error": {"message": "…", "type": "…", "code": "…"}} |
| Anthropic 协议端点 | {"type": "error", "error": {"type": "…", "message": "…"}} |
| 网关平台端点（/usage、/platform/billing） | {"error": {"type": "…", "message": "…"}} |
| 控制台 Web API | {"code": …, "message": "…"} |
协议端点保留上游原生错误结构，官方 SDK 的异常类型可直接使用。
HTTP 状态码矩阵
| 状态 | 类型示例 | 含义 | 客户端动作 |
|---|---|---|---|
| 400 | invalid_request_error | 参数非法/缺字段 | 修参数，勿重试 |
| 401 | authentication_error | Key 无效、禁用、格式错 | 检查/重建 Key |
| 402 | billing_error | 余额不足或在途预留不足 | 充值后重试 |
| 403 | permission_error | Key 未分配分组/功能未开放 | 分配分组/联系支持 |
| 404 | not_found_error | 模型不存在、responses 子路径不可转发、平台未开通 | 查 /v1/models |
| 409 | conflict_error | 并发/状态冲突（如异步任务状态） | 按提示退避 |
| 413 | invalid_request_error | 请求体超限 | 缩减输入/分块 |
| 429 | rate_limit_error | 分组 RPM / Key 并发或速率限制 | 读 Retry-After 指数退避 |
| 500 | api_error | 网关内部错误 | 重试并上报 |
| 502/504 | api_error | 上游连接/超时 | 指数退避重试 |
| 503/529 | overloaded_error | 上游过载 | 退避重试，关注渠道状态 |
流内错误
Anthropic 流在 HTTP 200 后仍可能下发 event: error；OpenAI 流可能以空内容提前 [DONE]。两者都按失败处理并按 流式（SSE） 的计费口径理解账单。
排错决策树
text
401 → Key 复制完整？已禁用？ → 重建
402 → 余额？ → 充值
403 → 分组分配？ → 控制台分配
404 → /v1/models 有该模型？ → 换模型/联系支持
429 → Retry-After 退避；持续 → 申请提额
5xx → 指数退避 ×3；仍失败 → 渠道状态页 + 工单（附时间窗/模型/请求 ID）