错误参考-Qoder CN 系列(Lingma)-阿里云帮助中心

错误信封格式

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

{
  "type": "error",
  "error": {
    "type": "<error_type>",
    "message": "<人类可读的错误描述>",
    "param": "<触发错误的参数名（可选）>"
  }
}

字段说明

字段	类型	必有	说明
`type`	string	是	固定为 `"error"`
`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",
  "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 — authentication_error

身份认证失败。

常见触发场景：

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

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key or token."
  }
}

# 触发示例：使用无效令牌
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）。

错误处理最佳实践

解析 error.type 用于程序化判断，而非 HTTP 状态码
记录 error.message 用于日志排查
检查 error.param 快速定位问题字段
4xx 错误不要重试（除非修改了请求参数）
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
  # 提取错误类型
  error_type=$(echo "$body" | python3 -c "import sys,json; print(json.load(sys.stdin)['error']['type'])")
  echo "API 错误: $error_type"
fi