NNexithDocs
状态控制台 ↗
概览与快速开始模型目录指南API 参考集成OAuth2 / OIDC

错误与限流

适用:全部 /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, 模型) 分桶,每分钟窗口。解析顺序:

  1. Key 级覆盖(控制台设置)
  2. 模型级默认
  3. 套餐默认
  4. 系统兜底: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,不产生费用
请求中途失败 预留全额退回
作业失败/取消 预留全额退回
流式已开始后断开 按已交付内容结算;零交付不收费