错误与限流
适用:全部
/v1端点
1. 错误格式#
所有非流式错误响应体统一为:
{
"error": {
"message": "The model 'gpt-4o' does not exist.",
"type": "invalid_request_error",
"code": "model_not_found"
}
}message人类可读,不保证稳定,不要用于逻辑判断。code机器可读,用于分支处理。type粗分类(authentication_error/rate_limit_error/billing_error/invalid_request_error/server_error)。
2. 错误码表#
| code | HTTP | 含义 | 处理建议 |
|---|---|---|---|
missing_api_key |
401 | 没带凭据 | 加 Authorization: Bearer |
invalid_api_key |
401 | Key 不存在/已吊销 | 换 Key |
invalid_token |
401 | JWT 过期或无效 | 重新登录 |
unauthorized |
401 | 其他认证失败 | 检查凭据 |
forbidden |
403 | 无权限(如 nx- Key 调 /v1/images/edits) |
改用 JWT |
invalid_request |
400 | 参数不合法 | 按 message 修正 |
model_not_found |
404 | 模型不存在/未开放 | 用 GET /v1/models 确认 |
not_found |
404 | 资源不存在或不属于当前用户 | 检查 ID |
conflict |
409 | 唯一性冲突 | 查询后重试 |
payload_too_large |
413 | 请求体/文件超限 | 缩小文件(文件 ≤10MB,全局 body ≤32MB) |
rate_limit_exceeded |
429 | RPM 超限 | 按 Retry-After 退避 |
token_rate_limit_exceeded |
429 | TPM 超限 | 按 Retry-After 退避 |
quota_exceeded |
429 | 套餐月配额用尽 | 升级套餐或等下月 |
insufficient_balance |
402 | 余额不足 | 充值后重试 |
inference_unavailable |
502 | 上游不可用(已尝试故障转移) | 可重试 |
model_overloaded |
503 | 上游过载 | 可重试 |
internal_error |
500 | 服务端异常 | 重试;持续失败请报障 |
上游的真实模型名、供应商 URL 与原始错误文本不会出现在响应中(不透明红线); 作业类错误只会返回固定文案。
3. 限流#
按 (API Key, 模型) 分桶,每分钟窗口。解析顺序:
- Key 级覆盖(控制台设置)
- 模型级默认
- 套餐默认
- 系统兜底:60 RPM / 40,000 TPM
429 响应头#
| Header | 说明 |
|---|---|
X-RateLimit-Limit-Requests |
RPM 上限 |
X-RateLimit-Remaining-Requests |
本分钟剩余请求数(超限时为 0) |
X-RateLimit-Reset |
窗口重置时间(Unix 秒) |
X-RateLimit-Limit-Tokens |
TPM 上限 |
X-RateLimit-Remaining-Tokens |
本分钟剩余 token(超限时为 0) |
Retry-After |
建议等待秒数 |
客户端建议#
import time, random
from openai import OpenAI, RateLimitError
def call_with_retry(fn, attempts=4):
for i in range(attempts):
try:
return fn()
except RateLimitError as e:
wait = float(e.response.headers.get("Retry-After", 1))
time.sleep(wait + random.uniform(0, 0.5))
raise- 只对 429 / 502 / 503 / 500 重试;4xx 参数错误重试无意义。
- 指数退避 + 抖动;尊重
Retry-After。 - 图片作业是异步的:提交返回 202 不代表生成完成,重试提交请复用
idempotency_key。
4. 幂等#
| 端点 | 幂等键 | 语义 |
|---|---|---|
/v1/images/generations |
idempotency_key(可选) |
同用户同键返回原作业 |
/v1/images/edits |
idempotency_key(可选) |
同上 |
文本对话请求没有幂等保证;网络重试会产生新的计费请求。
5. 计费相关状态#
| 场景 | 行为 |
|---|---|
| 余额不足 | 在触达上游前 402,不产生费用 |
| 请求中途失败 | 预留全额退回 |
| 作业失败/取消 | 预留全额退回 |
| 流式已开始后断开 | 按已交付内容结算;零交付不收费 |