模型接口的错误响应统一为 error 对象加顶层 trace_id；账单类接口的错误只有 error.code 与 error.message。排查问题时请提供 trace_id（或响应头 x-trace-id）。
错误响应格式
模型接口：
json
{
"error": {
"message": "Missing auth credential. Provide x-api-key: sk-* or Authorization: Bearer <token>.",
"type": "missing_auth_credential",
"code": 401,
"details": null
},
"trace_id": "4c9530c5-2bcc-472d-9c73-e07262bbbdb9"
}账单类接口：
json
{
"error": { "code": "invalid_request", "message": "request_id must be a valid UUID" }
}常见错误码
| HTTP 状态 | error.type | 触发条件 |
|---|---|---|
| 401 | missing_auth_credential | 没有带任何受支持的鉴权请求头 |
| 401 | invalid_api_key | x-api-key 或 x-goog-api-key 里的 Key 不正确、不完整或已删除 |
| 401 | invalid_bearer_token | Authorization: Bearer 里的 Key 不正确、不完整或已删除 |
| 400 | model_not_available | 模型 ID 不存在或暂不可用，对照 GET /v1/models 检查 |
| 400 | model_not_supported | 该模型当前不支持调用，按提示改用其他模型 |
| 400 | invalid_request_error | 请求不合法：模型与协议不匹配（如用 Responses API 调用 Claude）、纯文本模型收到图片输入、接口格式无效等，message 里有具体说明 |
| 402 或 400 | insufficient_balance | 账户余额不足。Anthropic 原生与 Gemini 原生端点返回 402，OpenAI 兼容端点（/v1/chat/completions、/v1/responses）返回 400；details.recharge_url 是充值地址 |
账单类接口另有：
| HTTP 状态 | error.code | 触发条件 |
|---|---|---|
| 400 | invalid_request | 参数无效，如时间范围错误、request_id 非 UUID |
| 404 | not_found | 请求记录不存在或无权访问 |
| 429 | rate_limit_exceeded | 请求过于频繁，稍后重试 |
| 500 | internal_error | 服务内部错误 |
排查建议
- ·收到 400 时先查看
error.message，其中会说明出错的字段或不匹配的类型 - ·400 表示请求本身有误，重试不会成功；429 与 5xx 可按指数退避重试
- ·流式请求的错误分"流开始前"与"流开始后"两种，见 流式输出