错误与状态码

请求失败时，接口返回非 2xx 状态码和 JSON 错误信息。

常见状态码

状态码	含义	建议处理
400	请求格式或参数错误	检查 JSON、字段类型与必填字段
401	鉴权失败	检查 API Key 是否正确、是否过期
402	可用额度不足	检查 API Key 限额、Coding Plan 窗口和钱包余额
403	无权访问该模型或功能	检查密钥的模型限制与账号状态
404	路径或模型不存在	检查路径拼写与模型 ID
409	请求与当前状态冲突	检查参数与账号状态
429	请求过于频繁或额度受限	降低频率，稍后重试
500	服务内部错误	稍后重试；持续失败请联系支持
502 / 503	上游服务暂时不可用	稍后重试
504	上游服务超时	稍后重试或缩短输入

错误响应示例

{
  "error": {
    "message": "invalid API key",
    "type": "invalid_request_error",
    "code": "unauthorized"
  }
}

不同协议的字段名可能不同。Anthropic Messages 使用 type: "error" 结构。

排查顺序

1. 确认 base URL 是否正确。
2. 确认 API Key 是否有效。
3. 调用 GET /v1/models 确认模型 ID。
4. 检查请求体是否为合法 JSON。
5. 如果使用流式响应，确认客户端支持 SSE。
6. 查看控制台请求日志中的错误信息。

更多内容见故障排查。

402 额度不足

错误码保持为 insufficient_balance。 原因明确时，error.param 包含以下值：

原因	含义	操作
api_key_limit	API Key 已达到累计消费限额	在令牌管理中调整限额或使用合适的 Key
plan_quota	Coding Plan 的窗口额度不足	在购买页面查看剩余额度及重置时间
wallet	钱包无可用余额	充值或兑换额度

{
  "error": {
    "code": "insufficient_balance",
    "param": "api_key_limit",
    "message": "API key spending limit reached"
  }
}

error.param 可能缺失，不要假定所有 402 都是钱包不足。 准入阶段拒绝的请求可能没有调用记录，请保留客户端错误响应。