错误码

错误响应格式、状态码与重试建议。

请求失败时，接口返回对应的 HTTP 状态码和 JSON 格式的错误信息。

错误格式

大多数错误使用 OpenAI 格式。请求刚进入、还没调用模型时的错误（如密钥无效）长这样，code 可能为空：

{
  "error": {
    "message": "无效的令牌 (request id: 2026102912000012345)",
    "type": "new_api_error",
    "code": ""
  }
}

进入模型调用阶段后的错误多一个 param 字段，code 会填具体的错误码：

{
  "error": {
    "message": "用户额度不足, 剩余额度: ... (request id: 2026102912000012345)",
    "type": "new_api_error",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

模型服务商返回的错误通常保留对方的 type、param 和 code。

调用 /v1/messages 时，请求进入模型调用阶段后的错误使用 Anthropic 格式：

{
  "type": "error",
  "error": { "type": "invalid_request_error", "message": "..." }
}

message 末尾的 request id 是这次请求的唯一编号，联系客服排查问题时请提供它。

状态码

状态码	含义	是否重试
`400`	请求格式错误：JSON 不合法、缺少必填参数、参数取值不对	否，修正请求
`401`	密钥无效：未提供、不存在、已过期或密钥自身额度用完	否，检查密钥
`403`	无权访问：密钥不能用该模型、账户余额不足、IP 不在白名单、账户被停用	否，调整设置或充值
`404`	接口地址错误，通常是 `/v1` 多写或少写	否，检查地址
`413`	请求体过大，常见于大图片或长文件	否，压缩内容
`429`	请求过于频繁	是，等待后重试
`500`	服务内部错误	是
`503`	该模型暂无可用渠道（`model_not_found`），或模型名写错	是，或换一个模型
其他	模型服务商返回的错误，状态码和信息会原样传回	视具体信息

各状态码的排查方法见常见问题与排错。

常见错误码

程序里建议按 code 判断错误类型，message 的文案可能调整：

`code`	状态码	含义
`model_not_found`	`503`	该模型在当前分组下没有可用渠道，或模型名写错
`insufficient_user_quota`	`403`	账户余额（或企业授信、订阅额度）不足
`pre_consume_token_quota_failed`	`403`	密钥剩余额度不够本次请求预扣
`access_denied`	`403`	请求 IP 不在密钥的白名单里
`invalid_request`	`400`	请求参数不合法，如图片张数超出范围

流式请求中的错误

流式输出开始之后才发生的错误，不会改变 HTTP 状态码（已经返回 200），而是以一条数据块的形式出现在流里。读取流时请检查数据块中是否包含 error 字段。

重试建议

只重试 429、500、503 和网络超时。其余 4xx 是确定性错误，重试也会失败。
使用指数退避加随机抖动，例如等待 1 秒、2 秒、4 秒，最多重试 3～5 次。
OpenAI、Anthropic 官方 SDK 自带重试，设置 max_retries 即可。

from openai import OpenAI

client = OpenAI(base_url="https://tokenfunc.com/v1", api_key="sk-xxxxxxxxxxxxxxxx", max_retries=3)