错误码与重试
区分模型 API 的 HTTP 错误和平台业务码，制定有限重试并提供可定位的报障信息。
先区分三类结果
模型 API 通常使用 HTTP 状态和 OpenAI 或 Anthropic 风格 error 描述失败；平台控制台 API 通常使用 code、message、data 包装业务结果。它们不是同一套错误码。
异步媒体还存在第三类状态：HTTP 请求成功，但任务仍在 PENDING、queued 或运行中；之后可能返回任务 FAILED / failed。创建 HTTP 200 不能作为最终生成成功的证据。
部分标准 Videos 处理分支使用平台业务错误包装，可能在 HTTP 200 中返回非零 code。稳健的 HTTP 客户端既要检查 HTTP 状态，也要识别响应中的业务码和任务终态；不能一律按 OpenAI SDK 异常判断成功。
错误响应格式
以下均为结构示意，文字与请求标识不是真实报错记录。OpenAI 风格错误：
{
"error": {
"message": "Insufficient balance. Please recharge your account.",
"type": "insufficient_quota",
"code": "insufficient_balance",
"request_id": "req_example",
"retryable": false
}
}Anthropic 风格错误：
{"type":"error","error":{"type":"invalid_request_error","message":"'max_tokens' is a required field"}}平台业务错误示意：
{"code":2001,"message":"参数错误","request_id":"req_example"}| 字段 | 解释 |
|---|---|
| HTTP 状态 | 传输层 / 接口失败类别，SDK 通常据此抛出异常 |
error.type | 错误分类，不等同于更具体的 error.code |
error.code | 具体原因，例如 insufficient_balance；可能不存在 |
error.retryable | 部分处理器提供的重试提示，仍需结合幂等性、额度和错误类别判断 |
顶层 code | 平台业务码；0 表示业务成功，非零应进入错误分支 |
request_id | 可能位于顶层、error 内或响应头；有值时保存以便排障 |
data | 平台成功数据或补充信息，可能省略，不应强依赖错误一定包含 data |
并非所有路径提供相同字段。比如 Messages 的处理器错误不保证 request_id 和 retryable，代理前置限流也可能采用更简的业务包装。解析未知字段应容错，但不能忽略已知失败信号。
HTTP 状态与处理建议
| HTTP | 常见原因 / 代码示例 | 建议 |
|---|---|---|
| 400 | JSON 格式、必填参数、模型不支持的参数；missing_model、invalid_image_url、embedding_not_supported | 修改请求，不原样重复提交 |
| 401 | missing_api_key、invalid_api_key、api_key_revoked | 检查使用的是完整 API Key，不是登录 Token；不要反复重试 |
| 402 | insufficient_balance，OEM 场景也可能是平台额度不足 | 核对余额、额度与服务提供方，不靠等待解决 |
| 403 | model_not_allowed、model_group_restricted，Messages 也可能只给错误类型与文字 | 检查 Key 的模型限制与用户组权限 |
| 404 | 模型不存在 / 不可用，任务不存在 / 已过期；各端点代码可能不同 | 核对模型 ID、端点、任务 ID，不假设所有 404 都是模型错误 |
| 429 | 频率限制、RPM 限制或 Key 额度已耗尽 | 先区分短期限流与 quota_exceeded；仅对可恢复限流退避 |
| 500 | 服务或通道配置错误，如 video_config_error | 记录响应与请求标识；配置错误需服务方处理 |
| 502 / 503 / 504 | 上游、网关或计费依赖不可用 / 超时，具体格式可能不同 | 在请求可安全重试且总时限允许时有限重试 |
不要把 type=insufficient_quota 固定解释为 HTTP 402：它也可用于权限或额度错误。也不要把每个 429 都当成“稍等就好”；Key 的 元限额达到上限不会因短暂退避恢复。
平台业务码
以下代码已在当前平台处理器中核对，但只是本页涉及的子集，不是全站统一穷举。控制台 API 可能以 HTTP 200 返回这些业务错误；认证中间件也可能直接返回非 2xx HTTP 状态。
code | 当前处理器中的含义 |
|---|---|
0 | 业务成功，从 data 读取数据 |
2001 | 参数错误或参数不符合要求 |
2002 | 指定资源不存在，例如模型或用户 |
4004 | 资源不存在、不能操作或不可访问；看 message，不能仅凭此码推断资源类型 |
5000 | 内部处理失败，如获取列表、创建 Key 或查询失败 |
5001 | 获取完整 API Key 失败 |
5002 | 创建时未保存可恢复的完整 Key，无法恢复，应按提示重新创建 |
5002 不是 HTTP 5002；它是业务字段的值。平台 Token、Key 管理与计费接口的参数和响应不要照搬模型 API 的格式。
完整诊断请求示例
下面请求 GET /v1/models 检查模型 API 的鉴权与基础 JSON 返回，不会提交生成任务。设置 GFW_API_KEY。cURL 同时显示状态和响应头；Python（依赖 requests）只对这个只读请求实施最多四次有界尝试，并识别业务错误。
curl --include --silent --show-error \
--max-time 30 \
https://api.gfw.net/v1/models \
-H "Authorization: Bearer ${GFW_API_KEY:?请先设置 GFW_API_KEY}" \
-H 'Accept: application/json'网络异常在本例直接上抛，避免用重试掩盖 DNS、代理或 TLS 配置问题。读取模型列表成功，只证明该请求与鉴权成功，不证明某个生成模型通道也能执行。
限流与安全重试
网关路由包含用户、Key 与 IP 层的限流，Key 配置还可包含每秒、RPM、TPM 和 元额度限制。运行配置、账号权限和上游限额可能不同，不应把某个默认数字当作账号的永久承诺。流式输出不会绕过限流，也不会让超限请求自动成功。
短期限流时优先遵守 Retry-After（如果提供），否则使用带随机抖动的指数退避，限制尝试次数与总等待时间。应用还应限制并发并排队，防止多个进程同时重试形成新的流量峰值。
对生成请求谨慎重试：连接超时可能发生在服务已受理之后。不要假设网关提供通用幂等键或自动去重；拿到异步任务 ID 后，只查询已有任务，不重复创建。工具操作需由应用实现幂等性；余额不足、参数错误、权限错误和配置错误都不应无差别自动重试。
流式开始后，错误可能出现在事件内部或表现为连接中断，HTTP 200 不再能说明最终成功。参阅 流式输出。
排障材料与相关文档
提交问题时提供：脱敏后的端点和模型 ID、请求时间及其时区、HTTP 状态、错误类型与代码、请求 / 任务 ID、是否流式、是否已重试，以及 SDK 或客户端名称。保留最小可复现参数，不发送 API Key、登录 Token 或包含敏感内容的完整请求。
先确认 URL 没有重复 /v1，模型 ID 没有厂商路径前缀，接口方法正确。404 HTML 页面通常应优先核对地址或代理配置；JSON 模型错误应核对目录和授权；已受理的媒体任务按任务状态排查。