Skip to main content
当你将 请求结构问题、认证问题、路径错误 和 可重试的平台故障 区分开来时，CometAPI 错误处理会变得最简单。结合 HTTP 状态码、error.code 和 error.message，判断是需要修复请求还是进行重试。

​
快速分诊

​
错误封装

许多 CometAPI 失败响应会使用如下错误体：
有些响应会将 code 留空。当状态码为 500 时，应将 error.code 和 error.message 作为决定性信号。

​
400 Bad Request

400 通常表示请求体在请求被正常处理之前未通过验证。 常见原因：
  • 缺少必填字段，例如 model
  • JSON 结构无效
  • 发送了类型错误的字段
  • 复用了所选 endpoint 不接受的提供商特定参数
从一个最小的、已知正常的请求开始，然后逐个加回可选字段。将 payload 与 API 参考中的 endpoint schema 进行对比。 使用如下最小请求：
将 your-model-id 替换为来自 CometAPI Models page 的任意当前 model ID。 不要假设每个格式错误的聊天请求都会返回 400。缺少 messages 这类必需聊天字段的情况，也可能表现为 500 且带有 error.code: invalid_request。

​
500 Internal Server Error

大多数 500 响应表示平台或提供商故障。对于聊天补全，一些格式错误的请求也可能表现为 500，同时仍携带 error.code: invalid_request。 其中一个例子是省略了 messages 的请求：
如果某个 500 响应带有 error.code: invalid_request，应将其视为请求问题：
  1. 修复请求体。
  2. 将 payload 与 endpoint schema 进行对比。
  3. 仅在修正 payload 后再重试。
如果某个 500 响应未指向无效请求，请保留 request id 并使用退避重试。

​
401 Invalid Token

Token 失败通常会表现为这样：
检查以下内容：
  1. 请求头必须严格为 Authorization: Bearer $COMETAPI_KEY。
  2. 确保你的应用没有从 .env、shell 历史记录或已部署的密钥存储中加载旧 key。
  3. 如果同一个请求中一个 key 失败而另一个 key 正常工作，应将其视为 token 问题，而不是 endpoint 问题。

​
403 Forbidden

403 最常见于以下几种情况：
  • 请求被平台侧规则阻止，例如 WAF 过滤
  • token 或路由无权使用所请求的 model 或请求结构
  • 所选 model 拒绝了你传递的某个高级参数
首先可以这样做：
  1. 使用一个已知可用的 model，发送一个非常简单的文本请求进行重试。
  2. 移除高级字段和 provider 特定参数，然后再逐步加回来。
  3. 如果响应中包含 request id，在联系支持之前先保留它。
如果消息中提到诸如 group 或 channel 这样的内部术语，应将其视为路由细节，而不是客户端侧首先要诊断的内容。实际上的修复方式仍然是先验证 token、model 和请求结构。

​
错误的 base URL 或错误的路径

在 Comet 上，路径错误可能表现为：
  • 重定向
  • 如果你的客户端会跟随重定向，则返回非 JSON 的 HTML 响应
  • SDK 内部出现解析错误
  • 请求始终无法正常到达 API 层
请严格使用以下 base URL：
推荐检查项：
  1. 确认 base URL 包含 /v1。
  2. 确认 endpoint 路径与文档完全一致。
  3. 在调试路径问题时，禁用自动跟随重定向。

​
413 Request Entity Too Large

如果你看到 413，首先应将其视为请求大小问题。常见原因包括：
  • 很大的 base64 负载
  • 内联嵌入的超大图像或音频
  • 非常大的 multipart 或 JSON 请求体
可以这样做：
  1. 缩小或压缩附加内容。
  2. 将大型任务拆分为更小的请求。
  3. 不要假设只有纯文本长度才会导致这个问题。

​
429 Too Many Requests

应将 429 视为可重试错误：
  1. 使用带抖动的指数退避。
  2. 降低突发并发量。
  3. 保持请求日志开启，以便你能看到是哪个路由和 model 先达到饱和。
如需可复用的重试模式，请参阅聊天补全中的退避示例。

​
503, 504, and 524

这些状态码属于服务端或超时类故障。 实用说明：
  • 503：路由或 provider 服务暂时不可用
  • 504 和 524：平台、边缘层或 provider 服务之间的超时类故障
可以这样做：
  1. 使用退避策略重试。
  2. 保留 request id、endpoint、model 和时间戳。
  3. 如果相同故障在多次重试后仍然重复出现，请带上这些上下文信息联系支持。

​
联系支持前

请先收集以下信息：
  • HTTP 方法
  • Endpoint 路径
  • Model ID
  • 脱敏后的请求体 JSON（对于大多数 API 调用，这是最有用的一项）
  • 如果失败的请求使用了查询参数，也请提供查询参数
  • 如果你的客户端捕获到了精确的响应体，也请提供
  • 完整的 HTTP 状态码
  • 精确的 error.message
  • 任何 request id
  • 大致时间戳
  • 相同请求是否可在另一个 model 或另一个 token 下正常工作
如果失败的路由接受的是文件上传（图像编辑、音频上传、视频生成等），而不是普通的 JSON 请求体，请发送对应的已提交负载：
  • 你随文件一同发送的字段名和文本值
  • 文件名、文件类型和大致文件大小
  • 文件是直接上传、通过 URL 引用，还是以 base64 嵌入
复现 bug 最有效的方式是提供精确的脱敏请求负载。对于大多数 API 调用，这意味着原始请求体 JSON。对于文件上传路由，这意味着字段列表加上文件元数据。
这会显著缩短支持处理时间。