Skip to main content
共通仕様

エラーリファレンス

Qoder Cloud Agents API のエラー形式、エラータイプ一覧、トラブルシューティングのベストプラクティス。

概要

Qoder Cloud Agents API は、すべてのエラーを統一されたエラーエンベロープ形式で返します。各エラーレスポンスには構造化された情報が含まれ、プログラム的な処理と問題のトラブルシューティングを容易にします。

エラーエンベロープ形式

すべてのエラーレスポンスは以下の JSON 構造に従います。 
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "<error_type>",
    "message": "<人間が読めるエラー説明>",
    "param": "<エラーをトリガーしたパラメータ名（オプション）>"
  }
}

フィールド説明

フィールド型必須説明
typestringはい固定値 "error"
request_idstringはいx-request-id から取得したリクエスト相関 ID、または生成された UUID
error.typestringはいエラータイプ識別子
error.messagestringはい人間が読めるエラー説明
error.paramstringいいえエラーをトリガーしたリクエストパラメータ名

エラータイプ一覧

HTTP ステータスコードerror.type説明
400invalid_request_errorリクエストパラメータが無効または欠落
401authentication_error認証失敗、トークンが無効または欠落
403permission_error認証は成功したが、対象リソースを操作する権限がない
404not_found_error対象リソースが存在しない
409conflict_errorリソース状態の競合（重複作成など）
500api_errorサーバー内部エラー

各エラータイプの詳細

400 — invalid_request_error

リクエスト形式またはパラメータが不正です。 よくあるトリガーシナリオ:
  • 必須フィールドの欠落（name など）
  • フィールド値の型が誤っている（string に number を渡したなど）
  • リクエストボディが 4MB のサイズ制限を超過
  • 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/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

401 — authentication_error

認証に失敗しました。 よくあるトリガーシナリオ:
  • Authorization ヘッダーが提供されていない
  • PAT または SAT の形式エラー
  • PAT の期限切れまたは取り消し、あるいは SAT の期限切れ
  • Bearer Token の代わりに 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/api/v1/cloud/agents \
  -H "Authorization: Bearer pt-invalid-token"

403 — permission_error

認証は通過したが、権限が不足しています。 よくあるトリガーシナリオ:
  • PAT または SAT に対象 Agent へのアクセス権限がない（他のユーザー/組織所属）
  • PAT または SAT の権限範囲が現在の操作をカバーしていない
  • アーカイブ済みかつロックされたリソースの操作試行
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "permission_error",
    "message": "You do not have permission to access this agent."
  }
}

# トリガー例: 他人の Agent へのアクセス \
curl -s https://api.qoder.com/api/v1/cloud/agents/agent_other_user_123 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

404 — not_found_error

対象リソースが存在しません。 よくあるトリガーシナリオ:
  • Agent / Session / Environment ID が存在しない
  • リソースが利用不可になった
  • URL パスのスペルミス
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "not_found_error",
    "message": "Agent not found: agent_nonexistent_123"
  }
}

# トリガー例: 存在しない Agent の照会 \
curl -s https://api.qoder.com/api/v1/cloud/agents/agent_nonexistent_123 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

409 — conflict_error

リソース状態の競合により、操作を実行できません。 よくあるトリガーシナリオ:
  • 同じ冪等キーで異なるリクエストボディの重複リクエスト
  • 終了済み Session への操作継続
  • 名前が一意のリソースの重複作成
{
  "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 エラーが発生した場合は、指数バックオフ戦略でリトライすることを推奨します（待機 1s → 2s → 4s）。

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

  1. error.type を解析 してプログラム的に判断する（HTTP ステータスコードではなく）。
  2. request_id と error.message をログに記録 してトラブルシューティングに使用する。
  3. error.param が存在する場合は確認 して問題のあるフィールドを特定する。
  4. 4xx エラーはリトライしない（リクエストパラメータを修正した場合を除く）。
  5. 5xx エラーはバックオフでリトライ（最大 3 回）。
# エラー処理付きリクエスト例 \
response=$(curl -s -w "\n%{http_code}" \
  https://api.qoder.com/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN")

# 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 の全体像。
はじめに
Agent の定義
Agent 環境の設定
Agent にタスクを委任する
Agent 連携
Agent コンテキストの管理
アカウント
ベストプラクティス
お知らせ
API リファレンス