常见错误码说明

HTTP 状态码

状态码	含义	处理建议
200	请求成功	—
400	请求参数错误	检查 JSON 格式、必填参数是否缺失
401	认证失败	检查 API Key 是否正确、是否已过期或被禁用
403	权限不足	该 Key 可能未被授权访问此模型
429	请求频率超限	降低请求频率，或联系客服提升 RPM 配额
500	服务端错误	重试请求；如持续出现请提交工单
502/503	上游模型服务异常	稍后重试；可切换到其他模型

错误响应格式

{
  "error": {
    "message": "Invalid API key provided: sk-nex-xxx...xxx.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

常见错误及解决方案

`invalid_api_key`

Invalid API key provided

原因： API Key 不正确或已被删除。

解决： 前往控制台确认 Key 状态，重新复制完整的 Key。

`model_not_found`

Model 'xxx' not found

原因： 模型 ID 拼写错误，或该模型未在您的套餐中启用。

解决： 检查模型 ID 是否正确（区分大小写）。可通过 /v1/models 端点查询完整模型列表。

`rate_limit_exceeded`

Rate limit exceeded

原因： 请求频率超过 RPM（每分钟请求数）配额。

解决： 降低请求频率，增加请求间隔。如需更高配额请联系客服。

`context_length_exceeded`

This model's maximum context length is xxx tokens

原因： 输入 + 输出的总 token 数超过模型上限。

解决： 减少输入内容长度，或降低 max_tokens 参数值。

重试策略建议

对于 429 和 5xx 错误，建议使用指数退避重试：

import time
import openai
 
def call_with_retry(client, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
        except openai.RateLimitError:
            wait = 2 ** attempt
            print(f"Rate limited, waiting {wait}s...")
            time.sleep(wait)
        except openai.APIStatusError as e:
            if e.status_code >= 500:
                wait = 2 ** attempt
                time.sleep(wait)
            else:
                raise
    raise Exception("Max retries exceeded")