錯誤參考 - AI Coding Assistant 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