:エラー

エラーエンベロープ

すべてのエラーレスポンスは、次の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) が欠落しています。
• フィールドの型が一致しません (文字列が想定されるところで数値が指定されているなど)。
• ボディが 4 MB の制限を超えています。
• 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 が使用されています。

{
  "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、セッション、または 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

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

一般的なトリガー：

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

{
  "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."
  }
}

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

1. HTTP ステータスコードではなく、error.type に応じて処理を分岐させてください。
2. 診断情報として error.message をログに記録してください。
3. 問題となっているフィールドを特定するために error.param を確認してください。
4. リクエストが変更されない限り、4xx エラーは再試行しないでください。
5. 5xx エラーは、エクスポネンシャルバックオフを使用して再試行してください (最大 3 回まで)。

# エラー処理を含むリクエスト
response=$(curl -s -w "\n%{http_code}" \
  https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT")

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