开发者文档
错误码大全
HTTP 状态码、业务错误码和重试策略。
HTTP 状态码
| 状态码 | 含义 | 建议 |
|---|---|---|
| 400 | 请求体或参数不合法 | 修正参数后再试 |
| 401 | 未鉴权或 Key 无效 | 检查 Bearer Token |
| 403 | 权限不足或模型不允许 | 检查角色、Key 白名单和模型可用范围 |
| 429 | 触发限流 | 指数退避后重试 |
| 500 | 平台内部错误 | 稍后重试并保留 request id |
| 502 / 503 | 上游不可用 | 可重试，必要时切换模型 |
业务错误码
| 错误码 | 语义 | 处理建议 |
|---|---|---|
INSUFFICIENT_BALANCE | 团队余额不足 | 到 Wallet 充值或联系 Owner |
KEY_DISABLED | Key 已禁用 | 更换 Key 或重新启用 |
MODEL_NOT_ALLOWED | 模型不在允许范围 | 调整 Key 白名单或 团队模型策略 |
RATE_LIMITED | 请求速率过高 | 使用指数退避和请求排队 |
UPSTREAM_FAILED | 上游返回失败 | 保留 request id 后重试或排查上游 |
重试策略
只对 429、502、503 和明确可重试的上游失败做重试。建议使用 1s、2s、4s 的指数退避，并设置最大重试次数，避免雪崩。