Skip to main content
通用约定

错误参考

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

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

错误信封格式

所有错误响应遵循以下 JSON 结构： 
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "<error_type>",
    "message": "<人类可读的错误描述>",
    "param": "<触发错误的参数名（可选）>"
  }
}

字段说明

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

错误类型一览

HTTP 状态码error.type说明
400invalid_request_error请求参数无效或缺失
401authentication_error认证失败，令牌无效或缺失
403permission_error认证成功但无权操作目标资源
404not_found_error目标资源不存在
409conflict_error资源状态冲突（如重复创建）
500api_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_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

401 — authentication_error

身份认证失败。 常见触发场景：
  • 未提供 Authorization 头
  • PAT 或 SAT 格式错误
  • PAT 已过期或被撤销，或 SAT 已过期
  • 使用了 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 或 SAT 无权访问目标 Agent（属于其他用户/组织）
  • PAT 或 SAT 权限范围不覆盖当前操作
  • 尝试操作已归档且锁定的资源
{
  "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_ACCESS_TOKEN"

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

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_ACCESS_TOKEN")

# 提取 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 的整体架构。
快速入门
构建 Agent
配置 Agent 环境
委派任务给 Agent
集成 Agent
管理 Agent 上下文
账户
最佳实践
公告
API 参考
错误参考 - Qoder