本页目录
错误响应结构
不论错误来自网关还是上游，返回体都是同一结构：
json
{
"error": {
"message": "insufficient balance for the requested maximum usage",
"type": "upstream_error",
"code": "insufficient_funds",
"retryable": false
}
}retryable 表示同样的请求稍后重发是否可能成功。排查问题时把响应头里的 X-Maxx-Request-ID 一并提供给支持，可以直接定位到那次调用。
HTTP 状态码
| 状态码 | 含义 | 是否重试 |
|---|---|---|
400 | 请求体不合法、参数不被支持，或模型 ID 不存在（model_not_supported） | 否，先改请求 |
401 | 没带 Key，或 Key 无效、已禁用、已过期 | 否 |
402 | 余额不足以覆盖本次请求的最大可能花费（insufficient_funds） | 否，先充值 |
403 | 该 Key 无权调用此模型（API_KEY_MODEL_DENIED） | 否 |
404 | 路径不存在 | 否 |
413 | 请求体过大，无法估算费用（request_too_large） | 否，先裁剪上下文 |
422 | 本次请求的预估费用超过单次上限（billing_limit_exceeded） | 否，调小 max_tokens |
429 | 并发超限或上游限流，见 Retry-After | 是，按退避重试 |
500 | 网关内部错误 | 是 |
502 | 上游返回异常，且所有候选渠道均失败 | 是 |
503 | 模型暂时没有可用渠道，或所有渠道都在满载 | 是，或换模型 |
常见 error.code
| code | 说明 | 处理 |
|---|---|---|
model_not_supported | 模型 ID 拼写错误或当前未开放 | 用 GET /v1/models 核对 |
API_KEY_MODEL_DENIED | Key 的「可用模型」里没有这个模型 | 在控制台修改这把 Key 的可用模型 |
insufficient_funds | 余额不足 | 充值，或调小 max_tokens |
context_length_exceeded | 输入超过模型上下文窗口 | 裁剪历史或换长上下文模型 |
unsupported_parameter | 该模型不支持传入的某个参数 | 去掉该参数，或换模型 |
api_key_concurrency_exceeded | 这把 Key 同时进行的请求过多 | 见限流说明 |
rate_limit_exceeded | 上游限流，且没有其他渠道可切换 | 退避后重试 |
provider_saturated | 该模型的所有渠道都在满载 | 稍后重试 |
no_available_provider | 该模型暂时没有可用渠道 | 稍后重试，或换模型 |
upstream_timeout | 上游响应超时 | 重试 |
content_policy_violation | 被上游内容策略拦截 | 调整 prompt |
推荐的重试策略
只对 408 / 429 / 5xx 重试，最多 3 次，采用指数退避加随机抖动。429 优先遵守响应头里的 Retry-After。
python
import time, random
from openai import OpenAI, APIStatusError
RETRY = {408, 429, 500, 502, 503}
def call_with_retry(client, **kwargs):
for attempt in range(3):
try:
return client.chat.completions.create(**kwargs)
except APIStatusError as e:
if e.status_code not in RETRY or attempt == 2:
raise
wait = (2 ** attempt) + random.random()
time.sleep(wait)注意
不要对 400 / 401 / 402 / 403 重试。这些错误重试多少次结果都一样，只会占用并发、拖慢正常请求。
联系我们
文档没写清楚，或者需要人工协助？按问题类型选一个渠道即可。