> ## 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 错误响应进行分类，并针对常见请求失败采取重试或修复步骤。

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

## 快速分诊

| Status                                   | 通常意味着什么                                                                        | 重试？   | 首个操作                                               |
| ---------------------------------------- | ------------------------------------------------------------------------------ | ----- | -------------------------------------------------- |
| `400`                                    | 请求在被正常处理之前未通过验证。                                                               | 否     | 验证 `model`、`messages`、JSON 结构和字段类型。                |
| `401`                                    | API key 缺失、格式错误或无效。                                                            | 否     | 检查 `Authorization: Bearer $COMETAPI_KEY`。          |
| `403`                                    | 访问被阻止，或者当前请求不被允许。                                                              | 通常不需要 | 使用一个已知正常的请求重试，并先移除特定于模型的字段。                        |
| Path mistake                             | base URL 错误或 endpoint 路径错误。在 Comet 上，这可能表现为 `301` 重定向或 HTML，而不是干净的 JSON `404`。 | 否     | 精确使用 `https://api.cometapi.com/v1`，并在调试时禁用自动跟随重定向。 |
| `429`                                    | 速率限制或临时饱和。                                                                     | 是     | 使用带抖动的指数退避。                                        |
| `500` with `error.code: invalid_request` | 格式错误的请求通过服务器状态响应暴露出来。                                                          | 否     | 在重试前修复请求体。                                         |
| `500`, `503`, `504`, `524`               | 平台、提供商或超时类故障。                                                                  | 是     | 使用退避重试，并保留请求 id。                                   |

## 错误封装

许多 CometAPI 失败响应会使用如下错误体：

```json theme={null}
{
	"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 进行对比。

使用如下最小请求：

```json theme={null}
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
```

将 `your-model-id` 替换为来自 [CometAPI Models page](/zh-Hans/overview/models) 的任意当前 model ID。

不要假设每个格式错误的聊天请求都会返回 `400`。缺少 `messages` 这类必需聊天字段的情况，也可能表现为 `500` 且带有 `error.code: invalid_request`。

## `500 Internal Server Error`

大多数 `500` 响应表示平台或提供商故障。对于聊天补全，一些格式错误的请求也可能表现为 `500`，同时仍携带 `error.code: invalid_request`。

其中一个例子是省略了 `messages` 的请求：

```json theme={null}
{
	"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 失败通常会表现为这样：

```json theme={null}
{
	"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 或路由无权使用所请求的 model 或请求结构
* 所选 model 拒绝了你传递的某个高级参数

首先可以这样做：

1. 使用一个已知可用的 model，发送一个非常简单的文本请求进行重试。
2. 移除高级字段和 provider 特定参数，然后再逐步加回来。
3. 如果响应中包含 request id，在联系支持之前先保留它。

<Warning>
  如果消息中提到诸如 `group` 或 `channel` 这样的内部术语，应将其视为路由细节，而不是客户端侧首先要诊断的内容。实际上的修复方式仍然是先验证 token、model 和请求结构。
</Warning>

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

在 Comet 上，路径错误可能表现为：

* 重定向
* 如果你的客户端会跟随重定向，则返回非 JSON 的 HTML 响应
* SDK 内部出现解析错误
* 请求始终无法正常到达 API 层

请严格使用以下 base URL：

```text theme={null}
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. 保持请求日志开启，以便你能看到是哪个路由和 model 先达到饱和。

如需可复用的重试模式，请参阅[聊天补全](/api/text/chat)中的退避示例。

## `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 嵌入

<Warning>
  复现 bug 最有效的方式是提供精确的脱敏请求负载。对于大多数 API 调用，这意味着**原始请求体 JSON**。对于文件上传路由，这意味着字段列表加上文件元数据。
</Warning>

这会显著缩短支持处理时间。