模型 API
错误码、429 与重试策略
区分鉴权、参数、模型、限流与上游错误，结合 request ID 制定有限重试策略。
更新于
按状态定位
| 状态 | 含义与处理 |
|---|---|
| 400 | JSON、消息或模型参数错误；修正请求，不要原样重试 |
| 401 | 缺少、失效或错误类型的凭证；检查 API Key |
| 402 | 余额或预算相关拒绝；检查钱包和限制 |
| 403 | 权限、分组或访问策略不允许；检查当前 Key |
| 404 | 路径、模型或资源不可用；核对目录与 ID |
| 413 | 请求体太大；缩小文件、图像或上下文 |
| 429 | 网关或供应商限流；读取错误和 Retry-After |
| 500 / 502 / 503 / 504 | 服务、上游或超时错误；保存请求 ID 并有限重试 |
保留错误体和请求 ID
网关错误统一返回 {"error":{"type":"ferrogate_error","code":"...","message":"...","request_id":"..."}}。供应商名称、URL、原始 code 和 message 不会返回；请保存 code、HTTP 状态、x-request-id、Retry-After（若有）。业务分支只使用 code。
Illustrative error (shape varies)
{"error":{"code":"invalid_request","message":"Request validation failed"}}429 来自哪里
429 只表示请求被限流，错误码会区分 gateway_capacity_exceeded 与 gateway_provider_rate_limited；两者都应遵守 Retry-After 或 retry-after-ms。
读取 Retry-After 或 retry-after-ms（若存在），结合错误 code 与使用历史判断。降低并发，减少单次输出预算，错开循环任务。若持续发生，提交时间、模型、任务 ID 和请求 ID。
完整错误码
以下是网关对外稳定错误码。任何 provider_*、upstream_* 或供应商原始错误都会转换为 gateway_* 码；内部诊断只写入服务端证据。
| 错误码 | 状态 | 场景与处理 |
|---|---|---|
| gateway_provider_circuit_open | 503 | 熔断开启；稍后重试 |
| gateway_provider_unavailable | 502/503 | 服务不可用；有限重试 |
| gateway_provider_timeout | 504 | 超时；退避重试 |
| gateway_provider_unreachable | 502 | 连接或传输失败；有限重试 |
| gateway_provider_authentication_failed | 502 | 供应商凭证失败；联系管理员 |
| gateway_provider_rate_limited | 429 | 供应商限流；遵守 Retry-After |
| gateway_provider_request_rejected | 502 | 供应商拒绝；修正参数 |
| gateway_provider_invalid_response | 502 | 响应格式无效；报告 request_id |
| gateway_provider_protocol_error | 502 | 协议不匹配；联系管理员 |
| gateway_provider_response_too_large | 502 | 响应超限；减少输出 |
| gateway_provider_stream_interrupted | 502 或流中 200 | 流未完成；标记未完成后谨慎重试 |
| gateway_provider_configuration_error | 502 | 网关配置缺失；联系管理员 |
| gateway_capacity_exceeded | 429 | 网关容量限制；降低并发 |
| gateway_timeout | 504 | 网关超时；退避重试 |
| gateway_request_rejected | 400 | 网关校验失败；修正请求 |
| gateway_internal_error | 500 | 异常；报告 request_id |
每种错误是否扣费
网关只按实际观测并写入用量记录的 token 结算。“网关扣费”指 Token4AI 钱包扣费；供应商可能在连接中断后自行计费，网关无法替供应商承诺。部分输出时，已观测 token 会照常结算。
| 类别 | 网关扣费 | 规则 |
|---|---|---|
| 请求校验、鉴权、模型、权限、配额 | 否 | 调用前拒绝，无供应商 usage |
| gateway_capacity_exceeded、gateway_timeout（调用前） | 否 | 未调用供应商 |
| gateway_provider_circuit_open | 否 | 熔断在调用前短路 |
| 供应商鉴权、限流、拒绝、无效响应、协议、超限 | 否（无 usage） | 错误响应不结算 token |
| 不可达或超时 | 否（无 usage） | 若已有部分流输出，按已观测 token |
| gateway_provider_stream_interrupted | 按已观测 token | 无 usage 为 0；已有 usage/输出照常结算 |
| 成功 2xx | 按实际 usage | 供应商 usage 或允许的本地回退估算 |
有限重试
- 只对明确可恢复的限流、超时或短暂服务错误重试；400/401/403 通常需要修改配置。
- 遵守服务端重试提示，使用指数退避与随机抖动，同时设置最大次数和整体截止时间。
- 明确由 SDK 或任务执行器的一层负责重试，避免层层相乘。
- 已经输出部分内容或执行过写入工具时，重试可能产生重复副作用和额外费用。