跳到主要内容

常见错误码

调用失败时，应同时查看 HTTP 状态码 和响应体中的 错误消息。同一个状态码可能对应多个原因；不同接口协议和 SDK 对错误字段、异常类名称的展示也可能不同。

快速排查​

建议按下面的顺序检查，大多数问题可以在前四步定位：

  1. 记录 HTTP 状态码和完整错误消息，但不要记录或发送完整 API 密钥。
  2. 确认请求地址、接口协议和路径是否匹配，尤其检查 /v1 或 /v1beta 是否重复或遗漏。
  3. 确认 API 密钥完整、已启用、未过期，并使用了当前协议要求的鉴权请求头。
  4. 从模型列表复制准确的模型 ID，检查密钥分组、模型限制和端点类型。
  5. 检查账户余额、密钥额度、请求频率、并发数和请求体大小。
  6. 在控制台的使用日志中核对实际请求时间、模型、接口和错误信息。

错误码速查​

HTTP 状态码含义常见原因是否适合直接重试
400 Bad Request请求参数错误JSON 格式错误、缺少必填字段、参数类型或取值无效否，修改请求后再试
401 Unauthorized身份验证失败未传密钥、密钥不完整、鉴权请求头格式错误否，先修正密钥或请求头
403 Forbidden无权执行请求密钥被禁用或过期、分组或模型权限不匹配、密钥限制阻止调用否，先修正权限或密钥配置
404 Not Found接口或资源不存在Base URL 或路径错误、模型 ID 错误、模型不在当前分组否，先修正地址或模型
413 Payload Too Large请求体过大图片、音频、Base64 数据或上下文超过网关限制否，缩小请求后再试
422 Unprocessable Entity参数校验失败JSON 可解析，但字段结构、类型或组合不符合接口要求否，修改参数后再试
429 Too Many Requests额度不足或请求受限账户余额或密钥额度不足、请求频率或并发数过高视错误消息而定
500 Internal Server Error服务内部异常平台或上游模型临时异常是，短暂等待后有限重试
502 Bad Gateway上游响应异常上游模型返回无效响应或连接中断是，短暂等待后有限重试
503 Service Unavailable服务暂时不可用服务繁忙、维护或上游模型暂不可用是，短暂等待后有限重试
504 Gateway Timeout上游响应超时模型生成时间过长或上游未及时响应是，但应降低请求规模并有限重试

错误消息比状态码更具体。例如，同样是 404，既可能是请求路径错误，也可能是模型不存在；同样是 429，既可能需要降低请求频率，也可能需要补充余额或调整密钥额度。

400 或 422：请求参数错误​

先读取错误消息中指出的字段，再检查：

  • 请求体是否为合法 JSON，属性名和字符串是否使用双引号。
  • 是否设置了 Content-Type: application/json；文件上传接口除外，应由客户端生成 multipart 请求头。
  • 是否提供当前接口要求的必填字段，例如 model、messages、input、contents 或 max_tokens。
  • 参数类型是否正确，例如数组没有误写为对象，数字没有误写为字符串。
  • 是否把一种协议的请求体发送到了另一种协议的接口。例如，OpenAI 使用 messages，Anthropic Messages 使用顶层 max_tokens，Gemini 使用 contents。
  • 当前模型是否支持工具调用、图片、音频、JSON Schema 或其他可选能力。

首次排查时，可以只保留必填参数发送最小请求，成功后再逐项加入可选参数。

401：身份验证失败​

常见检查项：

  • 使用的是控制台创建的 Bita API 密钥，而不是登录密码或其他平台的密钥。
  • OpenAI 兼容接口使用 Authorization: Bearer YOUR_BITA_API_KEY，Bearer 后有一个空格。
  • Anthropic 兼容接口使用 x-api-key，或按接入文档使用 Bearer 鉴权。
  • Gemini 兼容接口使用 x-goog-api-key。
  • 环境变量已在当前终端或服务进程中生效，没有多余的引号、换行或首尾空格。
  • SDK、代理或第三方工具没有用另一份旧配置覆盖当前密钥。

详细说明参见 Base URL 与身份验证。

403：密钥有效但无权调用​

收到 403 通常表示服务识别到了密钥，但当前请求不被允许。依次检查：

  • API 密钥是否已禁用或超过有效期。
  • 密钥所属分组是否支持目标模型。
  • 密钥是否设置了模型白名单、IP 限制或其他权限限制。
  • 目标模型和接口类型是否匹配，例如 Chat、Responses、Anthropic Messages 或 Gemini 原生接口。
  • 密钥自身的可用额度是否已用完。

不要仅通过重复创建密钥来规避问题；先根据错误消息和使用日志确认具体限制。

404：地址、路径或模型不存在​

先区分是“接口不存在”还是“模型不存在”：

现象优先检查
错误消息提到 route、path、endpoint 或页面不存在Base URL 和接口路径是否正确
错误消息提到 model、模型不存在或不可用模型 ID、密钥分组和模型端点类型

常用地址如下：

接口常用地址
OpenAI Chat Completionshttps://www.bita-api.com/v1/chat/completions
OpenAI Responseshttps://www.bita-api.com/v1/responses
Anthropic Messageshttps://www.bita-api.com/v1/messages
Gemini 原生接口https://www.bita-api.com/v1beta/models/MODEL_ID:generateContent

SDK 和第三方工具可能会自动追加接口路径。发现 /v1/v1/... 或 /v1beta/v1beta/... 时，应删除 Base URL 中重复的版本路径。详细排查参见 Base URL 与 /v1 路径问题和模型不可用。

413：请求体过大​

减小单次请求的体积后重试：

  • 压缩或降低图片分辨率，缩短音频，避免上传不必要的文件。
  • 不要在同一个请求中重复携带大段 Base64 数据。
  • 裁剪或总结过长的历史消息。
  • 把批量任务拆分为多个较小请求。

如果请求已经到达模型，但输入超过模型上下文限制，也可能返回 400 或上游定义的其他错误。此时应根据错误消息缩短输入或减少最大输出长度。

429：额度不足或触发限流​

先根据错误消息判断类型：

  • 提到 balance、quota、credit、额度或余额：检查账户余额、密钥额度和有效期。补充余额或调整额度后再试，等待本身通常不能解决问题。
  • 提到 rate limit、requests、tokens、concurrency、频率或并发：降低请求速度或并发数，并使用退避重试。
  • 只在特定模型上发生：该模型或上游渠道可能正处于高负载状态，可稍后重试或改用同类可用模型。

不要对所有 429 立即无限重试。额度类错误会持续失败，高频重试还会增加日志噪声和客户端负载。更多说明参见余额、额度与限流问题。

5xx：服务或上游模型异常​

500、502、503 和 504 多数属于临时服务异常，但也要先确认请求并非持续触发某个上游错误。建议：

  1. 保存请求时间、模型 ID、接口路径、状态码和脱敏后的错误消息。
  2. 等待数秒后重试，逐次延长等待时间，并设置最大重试次数。
  3. 对非流式请求，可尝试减少上下文长度、最大输出长度或复杂工具参数。
  4. 检查使用日志；如果只有一个模型失败，可测试另一个确认可用的模型。
  5. 多次重试仍失败时，停止自动重试并反馈问题。

没有 HTTP 状态码​

如果客户端只显示连接失败、DNS 错误、TLS 错误、连接重置或超时，说明可能没有收到完整的 HTTP 响应。这类问题不属于 API 错误码，优先检查：

  • 域名是否为 www.bita-api.com，本机是否可以解析并访问该域名。
  • 系统时间是否正确，代理、VPN、防火墙或证书检查是否拦截了 HTTPS。
  • SDK 的连接超时和读取超时是否过短。
  • 流式响应是否被反向代理或客户端缓冲、中途断开。

参见网络与超时问题。

识别错误响应​

OpenAI 兼容接口的错误响应通常具有下面的结构，具体字段可能因模型和上游服务而不同：

{
  "error": {
    "message": "具体错误信息",
    "type": "错误类型",
    "param": null,
    "code": "错误代码"
  }
}

Anthropic 或 Gemini 兼容接口、各语言 SDK 可能会把同一错误转换为不同 JSON 结构或异常类。因此不要只依赖 error.code 字符串；程序至少应保留 HTTP 状态码和可读的错误消息。

使用 cURL 调试时，可以通过 -i 同时查看响应头和响应体：

curl -i "https://www.bita-api.com/v1/models" \
  -H "Authorization: Bearer $BITA_API_KEY"
公开日志前先脱敏

不要把 Authorization、x-api-key、x-goog-api-key 或完整请求头粘贴到工单、群聊和公开仓库。即使密钥已经失效，也建议只保留开头和结尾少量字符用于辨认。

重试建议​

错误类型建议策略
400、401、403、404、413、422不要原样重试；先修正请求、地址、密钥、权限或模型
限流类 429优先遵循 Retry-After；否则使用带随机抖动的指数退避
额度类 429补充余额或调整密钥额度后再试
500、502、503、504使用带随机抖动的指数退避，并限制最大重试次数
连接中断或读取超时确认请求是否可能已被服务端处理，再决定是否重试

建议从 1 秒左右开始退避，例如等待 1、2、4、8 秒，并加入少量随机时间，避免多个客户端同时重试。生产环境还应设置总超时、最大次数和熔断策略。

流式请求中途失败时，本次输出是不完整的。重新请求应作为一次新的生成处理，不要把两次输出直接拼接；涉及有副作用的工具调用时，还应由应用通过业务 ID 做幂等控制。

反馈问题时提供什么​

如果仍无法解决，请提供：

  • 发生时间和时区。
  • 请求使用的接口路径和模型 ID。
  • HTTP 状态码、完整错误消息和 SDK 异常类型。
  • 是否为流式请求，以及问题能否稳定复现。
  • 控制台使用日志中的对应记录信息。
  • 已脱敏的最小请求示例。

请勿提供完整 API 密钥、登录密码或包含敏感业务数据的原始请求。