エラー - - Alibaba Cloud ドキュメントセンター

Qoder Cloud Agents API の統一エラーエンベロープフォーマット、エラータイプ、およびトラブルシューティングの方法について説明します。

重要

新しい Qoder CN ドキュメントサイトが公開されています。このサイトの内容は、最新の製品機能や変更を反映していない場合があります。最新の製品ドキュメントについては、docs.qoder.cn をご覧ください。

Qoder Cloud Agents API は、すべてのエラーを統一エラーエンベロープフォーマットで返します。各エラーレスポンスには、プログラムでの処理とトラブルシューティングのための構造化情報が含まれます。

エラーエンベロープフォーマット

すべてのエラーレスポンスは、次の JSON 構造に従います。

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "<error_type>",
    "message": "<human-readable error description>",
    "param": "<name of the parameter that triggered the error (optional)>"
  }
}

フィールドの説明

フィールド	型	必須	説明
`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 が指定されている)
リクエストボディが 4 MB のサイズ上限を超えている
不正な形式の 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.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 を使用している

{
  "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.cn/api/v1/cloud/agents" \
  -H "Authorization: Bearer pt-invalid-token"

403 — permission_error

認証には成功しましたが、必要な権限がありません。

主な原因：

PAT に、対象エージェントへのアクセス権限がない (エージェントが別のユーザーまたは組織に所属しているため)
PAT の権限スコープが現在の操作に対応していない
アーカイブされ、ロックされたリソースを操作しようとしている

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "permission_error",
    "message": "You do not have permission to access this 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

対象のリソースが存在しません。

主な原因：

エージェント、セッション、または環境の ID が存在しない
リソースが削除済みである
URL パスのタイプミス

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

# トリガー例：存在しないエージェントを照会している
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents/agent_nonexistent_123" \
  -H "Authorization: Bearer $QODER_PAT"

409 — conflict_error

リソースの状態が競合しているため、操作を実行できません。

主な原因：

同じべき等キーでリクエストが再試行されたが、リクエストボディの内容が異なっている
すでに終了したセッションに対して操作を実行しようとしている
一意の名前を持つべきリソースを重複して作成しようとしている

{
  "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 エラーが発生した場合は、エクスポネンシャルバックオフ (1 秒、2 秒、4 秒のように待機時間を空ける) を用いた再試行を行ってください。

エラー処理のベストプラクティス

プログラムでエラーを処理する際は、HTTP ステータスコードに依存せず、error.type を解析してください。
トラブルシューティングのためにrequest_id と 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: $error_type"
fi