错误码

HTTP 状态码

状态码	含义	处理建议
400	请求参数错误	检查 max_tokens 是否传入（必填）、messages 是否严格 user/assistant 交替、system 是否在顶层而非 messages 中。
401	API Key 缺失或错误	检查 Authorization: Bearer <API Key> 头。不要使用 x-api-key。
403	当前 Key 无权限访问该模型，或额度受限	联系运营方确认模型权限、余额或额度。
404	路径不存在或模型名不存在	确认是 /v1/messages；模型名与 /v1/models 返回一致。/v1/messages/count_tokens 当前不支持，返回 404 是预期行为。
429	请求过快或额度限制	降低并发，增加指数退避重试。
500	网关或上游异常	稍后重试；持续出现时联系运营方。
502 / 503 / 504	上游服务异常或超时	指数退避重试，必要时切换模型。

错误响应结构

错误响应使用 Anthropic 风格的 JSON：

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "param": "",
    "code": ""
  }
}

常见 type 值：

• invalid_request_error：请求格式或参数问题
• authentication_error：鉴权失败
• permission_error：无权限或额度不足
• not_found_error：路径或模型不存在
• rate_limit_error：限流
• api_error / overloaded_error：服务端错误

已知限制

• /v1/messages/count_tokens：当前网关未实现，请求会返回 404。客户端如有 token 预估需求，建议自行用 tokenizer 估算，或先发主请求按 usage 校准。
• 非流式 + tool_use：响应 content 数组可能为空（usage 仍正确）。建议工具调用一律使用流式（stream: true），见 工具调用。

重试策略

推荐策略

• 对 429、500、502、503、504 做指数退避重试。
• 起始退避 1 秒，每次翻倍，最多 5 次。
• 对非幂等业务（带支付/写库副作用）不要无脑重试。
• 流式请求中途断开，重试时建议从头发送，而不是续传。

日志最佳实践

• 记录：请求时间、模型名、HTTP 状态码、错误消息、业务 request id。
• 不要在日志中写完整 API Key（脱敏到前 4 / 后 4 即可）。
• 不要记录请求体的敏感字段（用户身份、支付信息）。
• 上游错误信息要原样保留：4xx 通常表示客户端可以修请求，5xx 通常表示服务端问题。

报告问题

持续遇到 5xx 或异常 4xx 时，把以下信息发到 info@aiqizhilian.tech：

• 出现时间（UTC 或东京时间均可）
• 调用模型名
• HTTP 状态码与响应 body（脱敏后）
• 客户端 IP（用于网关日志关联）
• 出现频率（偶发 / 持续 / 100%）

不要在工单中包含完整 API Key。