# 常见错误

https://omnimodel.me/docs/errors?lang=zh

出错时先看 HTTP 状态码和错误码，再按下表处理。错误信息的语言跟随请求头 `Accept-Language`（`zh-CN` 或 `en-US`）。

## 错误格式

| 接口 | 格式 |
| --- | --- |
| OpenAI 兼容 `/v1/*` | `{"error": {"message", "type", "code", "request_id"}}` |
| Anthropic 兼容 | `{"type": "error", "error": {"type", "message"}}`，没有机器可读的错误码 |
| Gemini 兼容 | `{"error": {"code", "message", "status"}}` |
| 平台接口 `/api/v1/*`、媒体任务 | `{"code", "message", "request_id", "details"}` |

联系支持时请附上 `request_id`。

## 常见错误码

| 错误码 | HTTP | 原因 | 处理 |
| --- | --- | --- | --- |
| `auth.invalid_key` | 401 | 密钥错误、已暂停、已过期或已撤销；或把密钥放在了 URL 参数里 | 检查密钥和请求头 |
| `auth.forbidden` | 403 | 模型不在这把密钥的可用模型里 | 修改密钥的可用模型 |
| `key.ip_denied` | 403 | 来源 IP 不在密钥的白名单里 | 修改 IP 白名单 |
| `key.spend_limit` | 402 | 达到密钥的每日或每月消费上限（OpenAI 格式为 `billing.key_limit_exceeded`） | 调高上限或等待周期切换 |
| `billing.insufficient_credit` | 402 | 余额不足以覆盖这次调用的预估费用 | 充值 |
| `billing.in_arrears` | 403 | 账户欠费 | 充值补足欠费 |
| `rate.limited` | 429 | 请求速率超限 | 退避后重试 |
| `concurrency.exceeded` | 429 | 同时进行的请求数超限 | 等待进行中的请求结束 |
| `model.unavailable` | 404 | 模型不存在、维护中、已下架，或不具备这个接口需要的能力 | 核对模型 ID 与[模型能力](/docs/capabilities) |
| `routing.not_applied` | 409 | 模型暂时没有可用的供应线路 | 稍后重试或换用其他模型 |
| `upstream.unavailable` | 503 | 上游服务出错或超时 | 稍后重试，失败的调用不收费 |
| `account.restricted` | 403 | 账户的 API 调用被暂停 | 查看站内通知或提交工单 |
| `content.prohibited.*` | 403 | 请求内容命中内容规则 | 修改内容，如有异议可按 `details` 里的链接申诉 |

## 重试建议

- 429 和 503 可以重试，建议指数退避并设置最大次数。
- 401、402、403、404 重试不会成功，需要先按上表处理。
- 非流式请求整体超时为 120 秒，长输出建议使用流式。

## 常见问题

### 返回 429 应该怎么重试？

rate.limited 和 concurrency.exceeded 都可以重试，建议指数退避并设置最大重试次数，同时减少并发请求。

### upstream.unavailable 会扣费吗？

不会。上游出错或超时的调用按失败处理，不收费，可以稍后重试。

### Anthropic 格式为什么看不到错误码？

Anthropic 协议的错误体只有类型和信息，没有机器可读的错误码；需要精确判断时可以改用 OpenAI 兼容接口。