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（如有），便于排障时提供给支持团队。