跳转到主要内容
当你将 请求问题、认证问题 和 可重试的平台问题 分开处理时，CometAPI 错误处理会变得最简单。本页是 CometAPI 官方错误指南，重点说明你可以首先从客户端侧验证的内容。
本指南基于对当前 CometAPI API 的实时检查。我们直接验证了 400、401 以及路径/base URL 失败。我们没有在受控测试中复现 413、429、500、503、504 或 524，因此针对这些状态码的建议刻意保持保守。

​
快速分诊

Status通常意味着什么重试？首要操作
400请求在成功路由之前就未通过校验。否校验 model、messages、JSON 结构以及字段类型。
401API key 缺失、格式错误或无效。否检查 Authorization: Bearer <COMETAPI_KEY>。
403访问被阻止，或当前请求不被允许。通常不需要使用一个已知正常的请求重试，并先移除模型特定字段。
Path mistakebase URL 或 endpoint 路径错误。在 Comet 上，这可能表现为 301 重定向或 HTML，而不是干净的 JSON 404。否严格使用 https://api.cometapi.com/v1，并在调试时禁用自动跟随重定向。
429限流或临时饱和。是使用带抖动的指数退避。
500, 503, 504, 524平台错误或超时类失败。是使用退避策略重试，并保留请求 id。

​
错误封装

CometAPI 当前返回的 JSON 错误封装如下： 
{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}
许多实时错误消息还会在 error.message 中包含一个 request id。当你需要支持时，请保存这个值。

​
400 Bad Request

当省略 model 时，我们从实时 API 观察到的结果： 
{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}
在实际中，400 通常表示请求体在平台将其路由到模型提供方之前就未通过校验。 常见原因：
  • 缺少必填字段，例如 model 或 messages
  • JSON 结构无效
  • 发送了类型错误的字段
  • 复用了所选 endpoint 不接受的提供方特定参数
处理方式：
  1. 从一个最小的已知正常请求开始。
  2. 逐个把可选字段加回去。
  3. 将请求体与 API 参考文档中的 endpoint schema 进行对比。
最小可用示例： 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
将 your-model-id 替换为 CometAPI Models page 中任意当前可用的模型 ID。

​
401 Invalid Token

使用无效 key 时，我们从实时 API 观察到的结果： 
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
需要检查的内容：
  1. 请求头必须严格为 Authorization: Bearer <COMETAPI_KEY>。
  2. 确保你的应用没有从 .env、shell 历史记录或已部署的密钥存储中加载旧 key。
  3. 如果同一个请求中一个 key 失败而另一个 key 可以成功，应将其视为 token 问题，而不是 endpoint 问题。

​
403 Forbidden

我们在有界测试中未稳定复现 403，因此不要把某一条旧的消息模板当作全部情况。 在当前的 Comet 文档中，403 最常见于以下几种情况之一：
  • 请求被平台侧规则拦截，例如 WAF 过滤
  • token 或路由无权使用所请求的 model 或请求形态
  • 所选 model 拒绝了你传入的某个高级参数
首先该怎么做：
  1. 使用已知可用的 model，发送一个非常简单的文本请求进行重试。
  2. 移除高级字段和 provider 特定参数，然后再逐步加回。
  3. 如果响应中包含 request id，在联系支持前请先保留它。
如果消息中提到诸如 group 或 channel 之类的内部术语，请将其视为路由细节，而不是客户端侧首先要排查的内容。实际可行的修复方式仍然是先验证 token、model 和请求形态。

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

这是旧页面中最不准确的部分。 在针对当前 Comet 端点的实时检查中：
  • 向 https://api.cometapi.com/chat/completions 发送请求时，返回了一个重定向到 https://www.cometapi.com/chat/completions 的 301
  • 向一个假的 API 路由发送请求，例如 https://api.cometapi.com/v1/not-a-real-endpoint，同样返回了一个重定向到 https://www.cometapi.com/v1/not-a-real-endpoint 的 301
这意味着路径错误可能表现为：
  • 重定向
  • 如果你的客户端会跟随重定向，则返回非 JSON 的 HTML 响应
  • SDK 内部出现解析错误
  • 请求始终无法正常到达 API 层
请严格使用以下 base URL： 
https://api.cometapi.com/v1
建议检查：
  1. 确认 base URL 包含 /v1。
  2. 确认端点路径与文档完全一致。
  3. 在调试路径问题时，禁用自动跟随重定向。

​
413 Request Entity Too Large

我们在有界测试中未复现 413，即使请求体是一个超大的 8 MiB JSON 请求体也是如此，因此旧解释中“prompt 太长”的说法过于狭隘。 如果你确实看到了 413，请首先将其视为请求大小问题。常见嫌疑包括：
  • 大型 base64 负载
  • 内联嵌入的超大图片或音频
  • 非常大的 multipart 或 JSON 请求体
该怎么做：
  1. 减少或压缩附加内容。
  2. 将大型任务拆分为更小的请求。
  3. 不要假设只有纯文本长度才会导致这个问题。

​
429 Too Many Requests

我们在一次有界并发探测中，对 24 个并行 GET /v1/models 请求未复现 429，因此具体阈值显然取决于路由、model 以及当前平台状态。 请将 429 视为可重试错误：
  1. 使用带抖动的指数退避。
  2. 降低突发并发量。
  3. 保持请求日志开启，这样你就能看到是哪个路由和 model 最先达到饱和。
如需可复用的重试模式，请参见聊天补全中的退避示例。

​
500、503、504 和 524

我们在有界测试中未复现这些状态码。它们应被归类为服务端或超时类故障，而不是用户错误。 实用指导：
  • 500：平台内部故障或 provider 侧故障
  • 503：路由或 provider 服务暂时不可用
  • 504 和 524：平台、边缘层或 provider 服务之间的超时类故障
该怎么做：
  1. 使用退避策略重试。
  2. 保留 request id、端点、model 和时间戳。
  3. 如果同样的故障在多次重试后仍然重复出现，请带上这些上下文信息联系支持。

​
联系支持之前

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