登录
文档导航
帮助与支持

错误码与重试

按 HTTP 状态码判断错误原因、是否重试和需要保留的信息。

本页目录
  1. 先保留诊断信息
  2. 状态码总表
  3. 400 Bad Request
  4. 401 Unauthorized
  5. 403 Forbidden
  6. 404 Not Found
  7. 408、504 与超时
  8. 429 Too Many Requests
  9. 5xx 服务端与上游错误
  10. 推荐重试策略
  11. 最小请求排障法
  12. 联系支持时提供

HTTP 状态码先告诉你错误属于请求、鉴权、权限、限流还是服务端。处理时先保存请求标识和最小错误信息，再决定修改配置、降低流量或有限重试。

先保留诊断信息

每次失败至少记录下面字段，但不要记录完整 API Key、Cookie、Authorization Header 或敏感提示词：

  • 请求发生的日期、时间和时区。
  • 客户端名称与版本。
  • 请求方法、脱敏后的 Base URL 和接口路径。
  • 完整模型名。
  • HTTP 状态码和错误类型。
  • 响应中的 request ID，或使用日志中的请求标识。
  • 当前 API Key 的分组，以及日志中的实际命中 group。
  • 是否流式、超时设置和本次重试次数。

请求标识可能出现在响应 Header、错误 JSON 或控制台使用日志中。它用于关联网关日志和上游调用，比单独提供错误截图更有效。

状态码总表

状态码 常见含义 默认是否重试 第一处理动作
400 请求体、参数、协议或模型能力不匹配 否 退回最小请求并检查字段
401 API Key 无效、过期、停用或认证格式错误 否 重新复制 Key 并检查 Header
403 用户分组、Key 或模型权限不足 否 查询 /v1/models 和 Key 限制
404 URL、/v1、接口或模型路由错误 否 核对实际完整 URL 和协议
408 客户端、网关或上游请求超时 有条件 缩小请求并有限重试
409 请求状态冲突或资源状态不允许 有条件 读取错误正文，确认是否可重复提交
413 请求体或上传内容过大 否 缩短上下文、压缩或拆分文件
422 请求结构可解析但语义无效 否 按错误字段修改请求
429 频率、并发、额度或上游限流 是 降低并发，遵守 Retry-After
500 网关或上游内部错误 是 保存 request ID，有限退避
502 上游响应无效或网关连接失败 是 有限退避，持续失败时换模型或联系支持
503 暂时无可用渠道或服务过载 是 延迟重试并降低并发
504 网关等待上游超时 是 增加合理超时、缩小请求、有限重试

错误 JSON 中的文字比状态码更具体。同一个 400 可能是 JSON 格式错误、参数不支持、上下文过长或协议错用，必须同时阅读错误正文。

400 Bad Request

常见原因：

  • JSON 语法错误或 Content-Type 不正确。
  • 把 Chat Completions 的 messages 发到 Responses API，或把 Responses 的 input 发到 Messages API。
  • 模型不支持工具、图片、音频、某个推理参数或指定响应格式。
  • max_tokens、max_output_tokens 等字段用错协议。
  • 上下文超过模型限制。

处理顺序：

  1. 删除工具、多模态、流式和所有非必要参数。
  2. 只保留模型、一条用户消息和很小的输出上限。
  3. 按目标协议的教程重新核对字段名。
  4. 最小请求成功后，每次只加回一个参数。

参数错误不会因为重试自动修复，不要对同一个 400 无限重发。

401 Unauthorized

检查：

  • 是否误粘贴了整段连接 JSON，而不是其中的纯 Key。
  • Key 前后是否带引号、空格或换行。
  • OpenAI 协议是否使用 Authorization: Bearer ...。
  • Anthropic 协议是否按客户端要求使用 x-api-key 或认证 Token。
  • Key 是否已停用、删除、过期或轮换。
  • 启动客户端的终端是否真的读到了环境变量。

不要把完整 Key 打印到日志来验证。可以只检查变量是否非空，或只显示首尾各少量字符。

403 Forbidden

鉴权身份通常已经识别，但请求没有相应权限。依次检查：

  1. GET https://api.zcloudapi.com/v1/models 是否包含目标模型。
  2. API Key 是否设置了模型白名单。
  3. Key 分组和用户可用分组是否允许该模型。
  4. 账户或 Key 是否有其他状态限制。

模型广场有该模型，不等于当前 Key 一定有权限。最终以当前 Key 的 /v1/models 为准。

404 Not Found

先检查实际发送的完整 URL：

正确示例: https://api.zcloudapi.com/v1/chat/completions
重复版本: https://api.zcloudapi.com/v1/v1/chat/completions
遗漏版本: https://api.zcloudapi.com/chat/completions
重复接口: https://api.zcloudapi.com/v1/responses/responses

如果 URL 正确，再确认模型是否使用这个协议。Claude Messages、OpenAI Responses、Chat Completions 和 Gemini native 的路径不能互换。完整地址规则见「接入地址选择」。

408、504 与超时

先区分：

  • 连接超时：DNS、网络、代理或防火墙问题。
  • 首字节超时：模型排队、推理时间或上游压力。
  • 流式中断：代理缓冲、客户端读取或上游连接中断。
  • 整体超时：客户端总超时小于模型实际完成时间。

处理方法：

  1. 用同一模型发送短输入、小输出、非流式请求。
  2. 确认客户端超时适合模型类型，推理和图片模型通常更慢。
  3. 检查代理是否支持长连接和 SSE。
  4. 只对幂等或可接受重复执行的请求有限重试。
  5. 持续超时时保存 request ID、模型和用时，再联系支持。

429 Too Many Requests

429 可能来自账户、API Key、网关、分组渠道或上游模型。处理时：

  1. 如果响应有 Retry-After，优先遵守。
  2. 降低并发和每秒请求数。
  3. 使用带随机抖动的指数退避。
  4. 设置最大重试次数和总重试时间。
  5. 检查余额、Key 额度和使用日志中的具体错误。

立即并发重试会进一步放大限流。生产服务需要排队、背压和失败预算，而不是无限重试。

5xx 服务端与上游错误

单次 500、502、503、504 通常可以有限重试，但要同时满足：

  • 请求允许重复执行，或者有业务幂等键。
  • 没有超出客户端总超时预算。
  • 重试使用退避和随机抖动。
  • 每次失败都保留同一业务操作的关联标识。

如果同一模型持续失败，而 /v1/models 和其他模型正常，记录模型、group、request ID、状态码和用时。不要提供完整 Key 或请求 Header。

推荐重试策略

400 / 401 / 403 / 404 / 413 / 422:
  不自动重试，先修复请求、地址或权限

408 / 429 / 500 / 502 / 503 / 504:
  在请求可重复的前提下重试
  第 1 次等待约 1 秒
  第 2 次等待约 2 秒
  第 3 次等待约 4 秒
  每次增加少量随机抖动
  同时受最大次数和总耗时限制

模型生成并不天然幂等。超时发生时，上游可能已经完成并产生费用，只是客户端没有收到结果。涉及外部工具、写数据库、发消息或付费动作的 Agent 请求，必须由业务层提供幂等控制。

最小请求排障法

  1. 不带凭据检查 https://api.zcloudapi.com 的 DNS、TLS 和连接。
  2. 使用目标 Key 请求 https://api.zcloudapi.com/v1/models。
  3. 从返回列表复制模型名。
  4. 使用对应协议发送单条文本、小输出、非流式请求。
  5. 查看 HTTP 状态、完整错误文字和 request ID。
  6. 到使用日志按时间核对模型、group、channel、用时和错误。
  7. 最小请求成功后，每次只恢复一个复杂参数。

联系支持时提供

  • 请求时间与时区。
  • 模型名、协议和脱敏 Base URL。
  • HTTP 状态码与完整错误文字。
  • request ID 或使用日志标识。
  • 日志中的 group、channel_id 或 channel_name。
  • 请求耗时、重试次数和客户端版本。

发送到 support@zcloudapi.com。不要发送完整 API Key、密码、Cookie、Authorization Header 或包含敏感业务数据的请求正文。