跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
快速分诊

Status它通常表示什么Retry?首个操作
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 with error.code: invalid_request格式错误的请求通过服务器状态响应暴露出来。否在重试前修复请求体。
500, 503, 504, 524平台、提供商或超时类故障。是使用退避重试，并保留 request id。

​
错误封装

许多 CometAPI 失败响应会使用如下错误体： 
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
有些响应会将 code 留空。当状态码是 500 时，将 error.code 和 error.message 作为判断依据。

​
400 Bad Request

400 通常表示请求体在请求能够被正常处理之前未通过验证。 常见原因：
  • 缺少必填字段，例如 model
  • JSON 结构无效
  • 发送了类型错误的字段
  • 复用了所选 endpoint 不接受的提供商特定参数
从一个最小的已知正常请求开始，然后逐个加回可选字段。将 payload 与 API 参考文档中的 endpoint schema 进行对比。 可以使用如下最小请求： 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
将 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 的请求： 
{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
如果 500 响应带有 error.code: invalid_request，应将其视为请求问题：
  1. 修复请求体。
  2. 将 payload 与 endpoint schema 进行对比。
  3. 仅在更正 payload 后再重试。
如果 500 响应未指向无效请求，请保留 request id 并使用退避重试。

​
401 Invalid Token

Token 失效通常会表现为如下形式： 
{
	"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 最常见于以下几种情况：
  • 请求被平台侧规则拦截，例如 WAF 过滤
  • 该 token 或路由无权使用所请求的模型或请求格式
  • 所选模型拒绝了你传入的某个高级参数
首先建议这样做：
  1. 使用一个已知可用的模型，发送一个非常简单的纯文本请求重试。
  2. 移除高级字段和 provider 专属参数，然后逐步加回。
  3. 如果响应中包含 request id，在联系支持前请先保留它。
如果消息中提到诸如 group 或 channel 之类的内部术语，请将它们视为路由细节，而不是客户端侧首先要诊断的内容。实际可行的修复方式仍然是优先检查 token、模型和请求格式。

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

在 Comet 上，路径错误可能表现为：
  • 重定向
  • 如果客户端会跟随重定向，则返回非 JSON 的 HTML 响应
  • SDK 内部出现解析错误
  • 请求始终无法正常到达 API 层
请严格使用以下 base URL： 
https://api.cometapi.com/v1
建议检查：
  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. 保持请求日志开启，以便查看是哪个路由和模型最先达到饱和。
如需可复用的重试模式，请参阅聊天补全中的 backoff 示例。

​
503、504 和 524

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

​
联系支持之前

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