错误处理

网关返回与 OpenAI 兼容的错误结构，并通过 DeepToken 错误分类帮助客户端判断责任归属与处理方式，无需解析错误文案。

错误结构

{
  "error": {
    "message": "可读的错误说明",
    "type": "category_name",
    "code": "specific_code"
  }
}

响应头 X-Gateway-Error-Category 会包含以下分类之一：

上游超时、过载和 5xx 错误会根据路由策略尝试其他候选渠道。客户端最终收到错误时，应结合 HTTP 状态、error.code、分类和子类型判断是否继续重试。

对于可能产生副作用的请求，请使用幂等键或在业务层记录请求状态，避免网络重试造成重复执行。

错误结构

{
  "error": {
    "message": "可读的错误说明",
    "type": "category_name",
    "code": "specific_code"
  }
}

响应头 X-Gateway-Error-Category 会包含以下分类之一：

常见错误码

401 invalid_api_key：API Key 不存在、已吊销或无效

403 model_not_allowed：API Key 的模型允许列表不包含该模型

403 ip_not_allowed：请求来源 IP 不在允许列表

402 org_wallet_empty：严格计费模式下组织钱包余额不足

403 budget_limit_exceeded：项目或 API Key 的预算上限已达到

429 rate_limit_exceeded：请求速率超过限制

503 no_available_channel：当前没有可用渠道可服务该模型

何时重试

对 platform_error 的 5xx 响应使用带抖动的指数退避。

对上游限流、过载或超时，仅在请求具备幂等性且响应明确允许时重试。

对 budget_limit_exceeded，需要调整预算或等待预算周期恢复；对 rate_limit_exceeded，等待对应限流窗口后重试。

对认证、权限、模型和参数错误，先修正配置或请求；原样重试不会成功。

对于可能产生副作用的请求，请使用幂等键或在业务层记录请求状态，避免网络重试造成重复执行。