Skip to main content
通用约定

错误参考

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

错误信封格式

401 认证错误与其他 HTTP 错误码使用不同的响应结构，确认的格式请参见本页「401 — 认证错误（Authentication Error）」小节。 其他错误码（400、403、404、409、500）是否同样使用 {"code":"...","message":"...","timestamp":"..."} 结构尚未确认，以下信封格式定义适用于上述错误码（待验证）。 其他错误码的错误响应遵循以下 JSON 结构： 
{
  "code": "<error_code>",
  "message": "<人类可读的错误描述>",
  "timestamp": "<Unix 毫秒时间戳>"
}

字段说明

字段类型必有说明
codestring是错误类型标识（如 TOKEN_INVALID）
messagestring是人类可读的错误描述
timestampstring是服务器处理请求的 Unix 毫秒时间戳

错误类型一览

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

各错误类型详解

400 — invalid_request_error

请求格式或参数不合法。 常见触发场景：
  • 缺少必需字段（如 name）
  • 字段值类型错误（如 string 传了 number）
  • 请求体超过 4MB 大小限制
  • JSON 格式错误
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required field: name",
    "param": "name"
  }
}

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

401 — TOKEN_INVALID

身份认证失败。 常见触发场景：
  • 未提供 Authorization 头
  • PAT 格式错误
  • PAT 已过期或被撤销
  • 使用了 x-api-key 而非 Bearer Token
{
  "code": "TOKEN_INVALID",
  "message": "invalid pt-token",
  "timestamp": "1782950157223"
}

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

403 — permission_error

认证通过但权限不足。 常见触发场景：
  • PAT 无权访问目标 Agent（属于其他用户/组织）
  • PAT 权限范围不覆盖当前操作
  • 尝试操作已归档且锁定的资源
{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "You do not have permission to access this agent."
  }
}

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

404 — not_found_error

目标资源不存在。 常见触发场景：
  • Agent/Session/Environment ID 不存在
  • 资源已被删除
  • URL 路径拼写错误
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Agent not found: agent_nonexistent_123"
  }
}

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

409 — conflict_error

资源状态冲突，操作无法执行。 常见触发场景：
  • 使用相同幂等键但不同请求体重复请求
  • 在已终止的 Session 上继续操作
  • 重复创建同名唯一资源
{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "A request with this idempotency key has already been processed with different parameters."
  }
}

500 — api_error

服务端内部错误。 常见触发场景：
  • 服务暂时不可用
  • 内部组件异常
  • 数据库连接超时
{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "An internal error occurred. Please try again later."
  }
}
遇到 500 错误时，建议使用指数退避策略重试（等待 1s → 2s → 4s）。

错误处理最佳实践

  1. 解析 code 字段用于程序化判断，而非 HTTP 状态码
  2. 记录 message 用于日志排查
  3. 4xx 错误不要重试（除非修改了请求参数）
  4. 5xx 错误使用退避重试（最多 3 次）
# 带错误处理的请求示例
response=$(curl -s -w "\n%{http_code}" \
  "https://api.qoder.com.cn/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
  if [ "$http_code" -eq 401 ]; then
    # 401 使用 code 字段，不含 error.type
    error_code=$(echo "$body" | python3 -c "import sys,json; print(json.load(sys.stdin)['code'])")
    echo "认证错误: $error_code"
  else
    error_code=$(echo "$body" | python3 -c "import sys,json; print(json.load(sys.stdin)['code'])")
    echo "API 错误: $error_code"
  fi
fi
操作指南
实践教程
API参考