> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # エラーリファレンス > Qoder Cloud Agents API のエラー形式、エラータイプ一覧、トラブルシューティングのベストプラクティス。 ## 概要 Qoder Cloud Agents API は、すべてのエラーを統一されたエラーエンベロープ形式で返します。各エラーレスポンスには構造化された情報が含まれ、プログラム的な処理と問題のトラブルシューティングを容易にします。 ## エラーエンベロープ形式 すべてのエラーレスポンスは以下の JSON 構造に従います。 ```json theme={null} { "type": "error", "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14", "error": { "type": "", "message": "<人間が読めるエラー説明>", "param": "<エラーをトリガーしたパラメータ名（オプション）>" } } ``` ### フィールド説明 | フィールド | 型 | 必須 | 説明 | | --------------- | ------ | --- | --------------------------------------------- | | `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 を渡したなど） * リクエストボディが 4MB のサイズ制限を超過 * JSON 形式エラー ```json theme={null} { "type": "error", "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14", "error": { "type": "invalid_request_error", "message": "Missing required field: name", "param": "name" } } ``` ```bash theme={null} # トリガー例: name フィールドの欠落 \ curl -X POST https://api.qoder.com/api/v1/cloud/agents \ -H "Authorization: Bearer $QODER_PAT" \ -H "Content-Type: application/json" \ -d '{}' ``` ### 401 — authentication\_error 認証に失敗しました。 **よくあるトリガーシナリオ:** * `Authorization` ヘッダーが提供されていない * PAT 形式エラー * PAT の期限切れまたは取り消し * Bearer Token の代わりに `x-api-key` を使用 ```json theme={null} { "type": "error", "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14", "error": { "type": "authentication_error", "message": "Invalid API key or token." } } ``` ```bash theme={null} # トリガー例: 無効なトークンの使用 \ curl -s https://api.qoder.com/api/v1/cloud/agents \ -H "Authorization: Bearer pt-invalid-token" ``` ### 403 — permission\_error 認証は通過したが、権限が不足しています。 **よくあるトリガーシナリオ:** * PAT に対象 Agent へのアクセス権限がない（他のユーザー/組織所属） * PAT の権限範囲が現在の操作をカバーしていない * アーカイブ済みかつロックされたリソースの操作試行 ```json theme={null} { "type": "error", "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14", "error": { "type": "permission_error", "message": "You do not have permission to access this agent." } } ``` ```bash theme={null} # トリガー例: 他人の Agent へのアクセス \ curl -s https://api.qoder.com/api/v1/cloud/agents/agent_other_user_123 \ -H "Authorization: Bearer $QODER_PAT" ``` ### 404 — not\_found\_error 対象リソースが存在しません。 **よくあるトリガーシナリオ:** * Agent / Session / Environment ID が存在しない * リソースが利用不可になった * URL パスのスペルミス ```json theme={null} { "type": "error", "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14", "error": { "type": "not_found_error", "message": "Agent not found: agent_nonexistent_123" } } ``` ```bash theme={null} # トリガー例: 存在しない Agent の照会 \ curl -s https://api.qoder.com/api/v1/cloud/agents/agent_nonexistent_123 \ -H "Authorization: Bearer $QODER_PAT" ``` ### 409 — conflict\_error リソース状態の競合により、操作を実行できません。 **よくあるトリガーシナリオ:** * 同じ冪等キーで異なるリクエストボディの重複リクエスト * 終了済み Session への操作継続 * 名前が一意のリソースの重複作成 ```json theme={null} { "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 サーバー内部エラーです。 **よくあるトリガーシナリオ:** * サービスの一時的な利用不可 * 内部コンポーネントの異常 * データベース接続のタイムアウト ```json theme={null} { "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 回）。 ```bash theme={null} # エラー処理付きリクエスト例 \ response=$(curl -s -w "\n%{http_code}" \ https://api.qoder.com/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 ``` ## 次のステップ Qoder Cloud Agents の全体像。