错误处理

错误结构

OpenAI 兼容的网关端点返回以下 JSON 格式的错误：

{
  "error": {
    "message": "Human-readable error description",
    "type": "error_code",
    "code": "error_code"
  }
}

运行时 type 与 code 始终相同。客户端代码应根据 HTTP 状态码和 error.code 来处理，不要依赖 message 文案。

Anthropic 兼容端点和 Gemini 兼容端点在协议处理或上游供应商返回错误时，可能保留对应协议的错误格式。

HTTP 状态分类

状态码	含义	是否重试
400	请求体、参数或字段不支持	不重试，先修正请求
401	缺少认证，或 Key 无效、已过期	不重试，提供有效 Key
403	权限不足、账号被停用或达到使用上限	不重试，检查权限或余额
404	当前 Key 不可用该模型或资源	不重试，刷新模型发现列表
413	请求体过大	不重试，减少输入
415	Content-Type 不支持	不重试，使用支持的类型
429	你自己的限额用完，或该模型的供给容量用完，看错误码区分	可重试；如有 Retry-After，以它为准
502	上游供应商返回错误	通常可按退避重试
503	模型不可用、供应商熔断或当前无可用路由	通常可按退避重试
504	网关或供应商超时	通常可按退避重试

公开错误码

完整列表见 错误码。常见错误码：

Code	状态码	含义
auth_required	401	缺少 API Key
auth_invalid	401	API Key 无效
auth_expired	401	API Key 已过期
spending_limit_exceeded	403	Key 使用上限或余额不足
model_not_found	404	当前 Key 不可用该模型
rate_limit_exceeded	429	达到你自己的 RPM/TPM 限制
supplier_rate_limited	429	你没有超限，是该模型的资源提供方达到了它们的上限
unsupported_request_field	400	实际路由不支持一个或多个请求字段
provider_error	502	上游供应商返回错误
model_unavailable	503	模型或路由暂时不可用
provider_timeout	504	上游供应商超时

重试策略

只对临时性失败做有上限的重试：

import random

def retry_delay_seconds(attempt: int, retryAfterHeader: str | None = None) -> float:
    if retryAfterHeader:
        return float(retryAfterHeader)
    return min(30, (2 ** attempt) + random.random())

• 对 429、502、503、504 使用指数退避和随机抖动。
• 如果响应包含 Retry-After 头，优先遵守它。
• 对认证错误、权限错误、使用上限、参数校验或请求体大小等错误，不要在不改变请求或配置的情况下重试。
• 记录状态码、error.code、请求 ID、模型和路由元数据。不要记录 prompt、文件内容、API Key 或上游凭证。

模型可用性

保存模型配置前，用同一个 API Key 调用 GET /v1/models。后续请求如果返回 model_not_found，请刷新该 Key 的路由策略和模型列表，不要凭空猜测备用模型名。