所有错误都是这个形状（同时兼容 OpenAI 与 Anthropic 客户端）：
{
"error": {
"message": "该密钥的额度已用完",
"type": "insufficient_quota",
"param": null,
"code": "key_quota_exhausted"
},
"type": "error"
}
| HTTP | code | 含义 | 怎么解决 |
|---|---|---|---|
| 401 | invalid_api_key | 没有带密钥，或密钥无效（已删除/改过） | 检查 Authorization: Bearer sk-... 拼写；密钥被删了就重建 |
| 403 | key_disabled | 密钥被禁用 | 控制台里重新启用或换一个密钥 |
| 403 | key_expired | 密钥超过有效期 | 修改有效期或新建密钥 |
| 403 | ip_not_allowed | 调用来源 IP 不在白名单内 | 改白名单，或关掉 IP 限制 |
| 403 | model_not_allowed | 密钥，或你所属团队给你设的「可用模型」里没有该模型 | 换一个模型；团队让你用的模型由主账号调整 |
| 403 | account_disabled | 账号被禁用 | 联系客服 |
| 403 | account_missing | 密钥对应的账号已不存在 | 新建账号与密钥 |
| 403 | team_disabled | 团队被禁用 | 联系团队管理员 |
| 402 | insufficient_balance | 余额不足（有团队的账号按两个钱包的合计判断） | 充值 |
| 404 | missing_model（400） | 请求里没写 model | 补上 model 字段 |
| 404 | — | 模型不存在 / 未上架 / 已下架 | 用「模型广场」里展示的模型名 |
| 404 | — | 接口路径不存在 | 对照《OpenAI 兼容格式》的端点表 |
| 429 | key_quota_exhausted | 该密钥的额度上限用满 | 提高上限或换密钥 |
| 429 | sub_quota_exhausted | 团队给你设的额度已用满，且你自己的余额也是 0 | 让团队主账号调高额度，或自己充值（额度只限制团队出的钱，不限制你花自己的） |
| 429 | rate_limit_exceeded | 触发频率限制 | 退避重试 |
| 502 | upstream_error | 上游全部失败 | 看 message 里的上游报错；换个模型或稍后再试 |
| 503 | — | 该模型没有可用渠道 | 联系运营配置渠道 |
「401 密钥无效」，但密钥明明是对的
检查是否把密钥写成了 sk- 加空格、换行；用 curl -H 时确认引号没被 shell 吃掉。也可以先用 GET https://aiapizz.com/v1/models 验证密钥本身是否有效（这个端点不消耗余额）。
「模型不存在」，但模型广场里能看到
模型名区分大小写，且必须完全一致；如果密钥配了「模型映射」，映射后的名字也要能对上。
返回体里的 model 字段和请求的不一样
正常现象：网关会把模型名替换成上游的部署名/真实模型名后再问上游，上游回什么就返回什么。计费与日志始终按你请求的模型名记录。
偶发 502，重试就好
多数是上游抖动或超时，网关已经自动换过渠道。若同一模型持续 502，把 X-Request-Id 和发生时间发给客服，后台能查到对应渠道的上游报错。
流式请求收到了完整 JSON（没有 data: 行）
三种格式、同格式与否，网关都会发事件流，所以这种情况只剩两个原因：
"stream": true；Gemini 要调 :streamGenerateContent 这个方法（方法名写在路径上，请求体里没有 stream 字段）。error.message 里的说明处理即可。如果确实带了 stream: true 却收到 HTTP 200 的完整 JSON，把 X-Request-Id 发给客服，后台能查到这一笔走的是哪条路径。
响应很慢但最终成功
可能是跨格式转换（要等上游生成完）、上游排队，或反向代理缓冲。先用 curl -N 直连对比一次，能区分问题在服务端还是代理层。