> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误参考

> Qoder Cloud Agents API 的统一错误信封格式、错误类型与排查实践。

Qoder Cloud Agents API 使用统一的错误信封格式返回所有错误。每个错误响应包含结构化信息，便于程序化处理和问题排查。

## 错误信封格式

所有错误响应遵循以下 JSON 结构：

```json theme={null}
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "<error_type>",
    "message": "<人类可读的错误描述>",
    "param": "<触发错误的参数名（可选）>"
  }
}
```

### 字段说明

| 字段              | 类型     | 必有 | 说明                                          |
| --------------- | ------ | -- | ------------------------------------------- |
| `type`          | string | 是  | 固定为 `"error"`                               |
| `request_id`    | string | 是  | 来自 `x-request-id` 的请求关联 ID；未传入时为服务端生成的 UUID |
| `error.type`    | string | 是  | 错误类型标识                                      |
| `error.message` | string | 是  | 人类可读的错误描述                                   |
| `error.param`   | string | 否  | 触发错误的请求参数名                                  |

## 错误类型一览

| HTTP 状态码 | `error.type`            | 说明            |
| -------- | ----------------------- | ------------- |
| 400      | `invalid_request_error` | 请求参数无效或缺失     |
| 401      | `authentication_error`  | 认证失败，令牌无效或缺失  |
| 403      | `permission_error`      | 认证成功但无权操作目标资源 |
| 404      | `not_found_error`       | 目标资源不存在       |
| 409      | `conflict_error`        | 资源状态冲突（如重复创建） |
| 500      | `api_error`             | 服务端内部错误       |

## 各错误类型详解

### 400 — invalid\_request\_error

请求格式或参数不合法。

**常见触发场景：**

* 缺少必需字段（如 `name`）
* 字段值类型错误（如 `string` 传了 `number`）
* 请求体超过 4MB 大小限制
* JSON 格式错误

```json theme={null}
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required field: name",
    "param": "name"
  }
}
```

```bash theme={null}
# 触发示例：缺少 name 字段
curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 401 — authentication\_error

身份认证失败。

**常见触发场景：**

* 未提供 `Authorization` 头
* PAT 格式错误
* PAT 已过期或被撤销
* 使用了 `x-api-key` 而非 Bearer Token

```json theme={null}
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key or token."
  }
}
```

```bash theme={null}
# 触发示例：使用无效令牌
curl -s "https://api.qoder.com/api/v1/cloud/agents" \
  -H "Authorization: Bearer pt-invalid-token"
```

### 403 — permission\_error

认证通过但权限不足。

**常见触发场景：**

* PAT 无权访问目标 Agent（属于其他用户/组织）
* PAT 权限范围不覆盖当前操作
* 尝试操作已归档且锁定的资源

```json theme={null}
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "permission_error",
    "message": "You do not have permission to access this agent."
  }
}
```

```bash theme={null}
# 触发示例：访问他人的 Agent
curl -s "https://api.qoder.com/api/v1/cloud/agents/agent_other_user_123" \
  -H "Authorization: Bearer $QODER_PAT"
```

### 404 — not\_found\_error

目标资源不存在。

**常见触发场景：**

* Agent/Session/Environment ID 不存在
* 资源已被删除
* URL 路径拼写错误

```json theme={null}
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "not_found_error",
    "message": "Agent not found: agent_nonexistent_123"
  }
}
```

```bash theme={null}
# 触发示例：查询不存在的 Agent
curl -s "https://api.qoder.com/api/v1/cloud/agents/agent_nonexistent_123" \
  -H "Authorization: Bearer $QODER_PAT"
```

### 409 — conflict\_error

资源状态冲突，操作无法执行。

**常见触发场景：**

* 使用相同幂等键但不同请求体重复请求
* 在已终止的 Session 上继续操作
* 重复创建同名唯一资源

```json theme={null}
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "conflict_error",
    "message": "A request with this idempotency key has already been processed with different parameters."
  }
}
```

### 500 — api\_error

服务端内部错误。

**常见触发场景：**

* 服务暂时不可用
* 内部组件异常
* 数据库连接超时

```json theme={null}
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "api_error",
    "message": "An internal error occurred. Please try again later."
  }
}
```

<Note>遇到 500 错误时，建议使用指数退避策略重试（等待 1s → 2s → 4s）。</Note>

## 错误处理最佳实践

1. **解析 `error.type`** 用于程序化判断，而非 HTTP 状态码
2. **记录 `request_id` 和 `error.message`** 用于日志排查
3. **如果存在，检查 `error.param`** 快速定位问题字段
4. **4xx 错误不要重试**（除非修改了请求参数）
5. **5xx 错误使用退避重试**（最多 3 次）

```bash theme={null}
# 带错误处理的请求示例
response=$(curl -s -w "\n%{http_code}" \
  "https://api.qoder.com/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT")

# 提取 HTTP 状态码
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -ge 400 ]; then
  # 提取错误类型
  error_type=$(echo "$body" | python3 -c "import sys,json; print(json.load(sys.stdin)['error']['type'])")
  echo "API 错误: $error_type"
fi
```

## 下一步

<CardGroup cols={2}>
  <Card title="概览" icon="rocket" href="/zh/cloud-agents/overview">
    了解 Qoder Cloud Agents 的整体架构。
  </Card>
</CardGroup>