メインコンテンツへスキップ

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

​
エラーエンベロープ形式

すべてのエラーレスポンスは以下の JSON 構造に従います。 
{
  "type": "error",
  "error": {
    "type": "<error_type>",
    "message": "<人間が読めるエラー説明>",
    "param": "<エラーをトリガーしたパラメータ名（オプション）>",
    "feature": "<必要な機能識別子（501 エラーのみ）>",
    "available_from": "<機能が利用可能な Beta 識別子（501 エラーのみ）>"
  }
}

​
フィールド説明

フィールド型必須説明
typestringはい固定値 "error"
error.typestringはいエラータイプ識別子
error.messagestringはい人間が読めるエラー説明
error.paramstringいいえエラーをトリガーしたリクエストパラメータ名
error.featurestringいいえ有効化が必要な機能（501 専用）
error.available_fromstringいいえ機能に対応する Beta 識別子（501 専用）

​
エラータイプ一覧

HTTP ステータスコードerror.type説明
400invalid_request_errorリクエストパラメータが無効または欠落
401authentication_error認証失敗、トークンが無効または欠落
403permission_error認証は成功したが、対象リソースを操作する権限がない
404not_found_error対象リソースが存在しない
409conflict_errorリソース状態の競合（重複作成など）
500api_errorサーバー内部エラー
501feature_not_available機能が有効化されておらず、Beta ヘッダーによる有効化が必要

​
各エラータイプの詳細

​
400 — invalid_request_error

リクエスト形式またはパラメータが不正です。 よくあるトリガーシナリオ:
  • 必須フィールドの欠落（name など）
  • フィールド値の型が誤っている（string に number を渡したなど）
  • リクエストボディが 32MB のサイズ制限を超過
  • JSON 形式エラー
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required field: name",
    "param": "name"
  }
}

# トリガー例: name フィールドの欠落 \
curl -X POST https://openapi.qoder.sh/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 を使用
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key or token."
  }
}

# トリガー例: 無効なトークンの使用 \
curl -s https://openapi.qoder.sh/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://openapi.qoder.sh/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://openapi.qoder.sh/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）。

​
501 — feature_not_available

リクエストされた機能がまだ有効化されておらず、Beta ヘッダーによる有効化が必要です。 よくあるトリガーシナリオ:
  • Beta ヘッダーに対応する機能識別子が欠落
  • 期限切れの Beta 識別子の使用
{
  "type": "error",
  "error": {
    "type": "feature_not_available",
    "feature": "managed-agents",
    "available_from": "managed-agents-2026-04-01"
  }
}

# トリガー例: Beta ヘッダーの欠落 \
curl -s https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT"

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

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