错误与限额
所有路由——/v1、/v1beta 以及未鉴权端点——都返回同一种错误结构：
{ "error": { "message": "invalid api key", "type": "authentication_error", "code": "invalid_api_key", "param": null } }| 字段 | 用途 |
|---|---|
| code | 用它做分支。稳定、机器可读、具体。 |
| type | OpenAI 兼容的分类，给已经在 switch 的客户端。 |
| message | 给人看。已脱敏，但格式自由、不构成契约。 |
| param | 当前始终为 null，保留是为兼容 OpenAI SDK。 |
type 取值为 invalid_request_error、authentication_error、permission_error、not_found_error、rate_limit_error、insufficient_quota、upstream_error、timeout_error、server_error。message 在离开我们之前会做清洗：供应商名称、base URL、上游模型名与凭证都不会出现。上游的原始文本只留在我们的日志里——这就是为什么工单里贴 X-Request-Id 比贴 message 更有用。
状态码
| 状态码 | 含义 |
|---|---|
| 400 | 请求格式错误：字段缺失、枚举非法、URL 不可用 |
| 401 | 没有凭证、key 未知或已停用，或账号被停用 |
| 402 | 积分不足 |
| 403 | OAuth token 缺少该路由所需 scope |
| 404 | 未知路由、未知模型，或任务不属于你 |
| 409 | 幂等冲突，或在资产存在之前请求 /content |
| 413 | 请求体或上传文件超过上限 |
| 425 | 相同的幂等请求仍在准备中——稍后重试 |
| 429 | 触发速率、并发或未完成任务数上限 |
| 499 | 调用方在我们完成前断开 |
| 500 | 我方缺陷 |
| 502 | 上游失败或返回不可用内容 |
| 503 | 当前没有可用供应商，或我们的数据库短暂不可读 |
| 504 | 上游未及时响应 |
402 与 503 都不能用同一形状重试：402 需要积分；而 no_available_provider 或 precheck_failed 导致的 503 应当带退避重试，因为它表示我方短暂无法服务，而不是你的请求写错了。
限流：两条，都按 API key 计
| 限制 | 默认值 | 被拒时 |
|---|---|---|
| 每分钟请求数 | 60 | 429 rate_limited，Retry-After: 60 |
| 并发请求数 | 15 | 429 too_many_concurrent_requests，Retry-After: 1 |
这是默认值，部署方可以调高。实现上分别是令牌桶与信号量——请求会被拒绝，而不会被排队。OAuth access token 没有 key 记录，因此按账号限流。另有一条限制只作用于异步媒体任务（未完成任务数）。
中文内容导航
继续阅读
常见问题
message 里为什么看不到上游报错原文？
出于安全与脱敏考虑，供应商名称、URL 与模型名不会外泄；原文只存在我们的日志里。用 X-Request-Id 定位即可。
收到 429 应该怎么处理？
按 Retry-After 退避，并把工作合并成更少、更长的任务；并发提交时通常先撞到未完成任务上限。
反复 504 怎么办？
重试一次；若持续出现，把该步骤切换到另一个模型或供应商，而不是无限重试同一家。