错误参考

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

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

​

错误信封格式

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

{
  "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 格式错误

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

# 触发示例：缺少 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

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

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

​

403 — permission_error

认证通过但权限不足。

常见触发场景：

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

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

# 触发示例：访问他人的 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 路径拼写错误

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

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

​

409 — conflict_error

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

常见触发场景：

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

{
  "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

服务端内部错误。

常见触发场景：

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

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

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

​

错误处理最佳实践

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

# 带错误处理的请求示例
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

​

下一步

概览

了解 Qoder Cloud Agents 的整体架构。