错误码

出错时，接口返回标准 OpenAI 错误结构：

{
  "error": {
    "message": "具体的错误描述信息",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

HTTP 状态码

HTTP 状态码	含义	常见原因与处理方式
400	请求无效	参数缺失、JSON 格式错误或参数超出模型限制，按 message 字段描述修正请求体
401	未授权	令牌缺失、错误或已被禁用，检查 Authorization 请求头
403	无权限 / 额度不足	令牌额度耗尽、模型不在可用分组或 IP 不在白名单，到控制台检查令牌设置与余额
404	未找到	模型名拼写错误或接口路径不存在，用 /v1/models 核对模型 ID
422	参数校验失败	请求体格式正确但参数值不合法，按 message 调整参数
429	请求过快	触发速率限制，按指数退避策略重试
500	服务端错误	平台内部异常，稍后重试；持续出现请联系客服
503	上游服务不可用	上游模型渠道波动，稍后重试；如持续建议切换模型

错误类型（type）

type	说明
invalid_request_error	请求参数有误
authentication_error	鉴权失败
permission_error	无权限访问该资源
not_found_error	资源不存在
rate_limit_error	速率限制
api_error	API 内部错误
overloaded_error	服务过载

常见错误代码（code）

code	说明
invalid_api_key	API Key 无效
model_not_found	模型不存在或无权访问
context_length_exceeded	输入超出模型最大上下文长度
max_tokens_exceeded	max_tokens 超出模型限制
insufficient_quota	账户余额不足
rate_limit_exceeded	请求频率过高
content_filter	内容被安全过滤器拦截

重试建议

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

import time
import httpx

def chat_with_retry(client, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt  # 1s, 2s, 4s
            print(f"请求失败，{wait}s 后重试... ({e})")
            time.sleep(wait)

WARNING

对于 400、401、403、404 这类客户端错误，重试没有意义，应直接检查请求参数或令牌配置。