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

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 は 冪等キー（Idempotency Key） を通じて、書き込み操作の安全なリトライをサポートします。ネットワークが不安定な場合やクライアントタイムアウトが発生した場合でも、冪等キーを使用することで、リソースの重複作成や操作の重複実行を回避できます。

​
ヘッダー形式

等価な 2 種類のヘッダー名がサポートされています。
ヘッダー名説明
Idempotency-Key標準形式
X-Idempotency-KeyX- プレフィックス付きの互換形式
両者の機能は完全に同じで、どちらを選択してもかまいません。 
# 方式 1: 標準形式
Idempotency-Key: unique-request-id-001

# 方式 2: X- プレフィックス形式
X-Idempotency-Key: unique-request-id-001
グローバルな一意性を保証するため、UUID v4 を冪等キーの値として使用することを推奨します。

​
適用範囲

冪等キーは 書き込み操作にのみ 有効です。
HTTP メソッド冪等キーのサポート説明
POSTはいリソースの作成
PUTはいリソースの更新
DELETEはいリソースの削除
GETいいえ読み取り操作は本質的に冪等であり、この機構は不要

​
使用例

​
Agent の作成（冪等キー付き）

# UUID を冪等キーとして使用 \
curl -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "my-agent",
    "model": "qoder-sonnet-latest"
  }'

​
スクリプトで冪等キーを生成

# UUID を自動生成してリクエストを発行 \
IDEMPOTENCY_KEY=$(uuidgen | tr '[:upper:]' '[:lower:]')

curl -X POST https://openapi.qoder.sh/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "agent_id": "agent_abc123"
  }'

echo "冪等キー: $IDEMPOTENCY_KEY"

​
重複リクエストの動作

​
同じ冪等キー + 同じリクエストボディ

サーバーは初回リクエストのレスポンス結果を直接返し、操作を繰り返し実行しません。 
# 1 回目のリクエスト → リソース作成、201 を返す \
curl -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-001" \
  -d '{"name": "test-agent", "model": "qoder-sonnet-latest"}'

# 2 回目のリクエスト（同じ key + 同じ body）→ 初回の結果を直接返す \
curl -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-001" \
  -d '{"name": "test-agent", "model": "qoder-sonnet-latest"}'

​
同じ冪等キー + 異なるリクエストボディ

サーバーは 409 conflict_error を返し、実行を拒否します。 
{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "A request with this idempotency key has already been processed with different parameters."
  }
}
ユニークなビジネス操作ごとに、独立した冪等キーを使用してください。異なるリクエストで同じ key を再利用しないでください。

​
冪等キーのライフサイクル

機能説明
有効期間冪等キーは初回使用後 24 時間保持されます
期限切れ後同じ key は新規リクエストとして再実行されます
適用範囲PAT（アカウント）ごとに分離。異なるアカウントの同じ key は互いに影響しません

​
ベストプラクティス

​
1. 冪等キーを使用するタイミング

  • 重要なリソース（Agent、Session）の作成時に 強く推奨
  • ネットワーク不安定な環境下でのすべての書き込み操作
  • 自動化スクリプトでのバッチ操作

​
2. Key の生成戦略

戦略適用シナリオ例
UUID v4汎用シナリオ550e8400-e29b-41d4-a716-446655440000
ビジネス ID 組み合わせビジネスレベルでの重複排除create-agent-project42-env-prod
タイムスタンプ + ランダム数シンプルなシナリオ1717200000-abc123

​
3. リトライ付きの完全な例

#!/bin/bash
# Session の作成、冪等キーとリトライロジック付き
IDEMPOTENCY_KEY=$(uuidgen | tr '[:upper:]' '[:lower:]')
MAX_RETRIES=3

for i in $(seq 1 $MAX_RETRIES); do
  response=$(curl -s -w "\n%{http_code}" \
    -X POST https://openapi.qoder.sh/api/v1/cloud/sessions \
    -H "Authorization: Bearer $QODER_PAT" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
    -d '{"agent_id": "agent_abc123"}')

  http_code=$(echo "$response" | tail -1)
  body=$(echo "$response" | sed '$d')

  # 成功またはクライアントエラー（リトライ不要）
  if [ "$http_code" -lt 500 ] && [ "$http_code" != "429" ]; then
    echo "$body"
    break
  fi

  # サーバーエラー、安全にリトライ（冪等キーが重複作成を防止）
  echo "$i 回目のリクエスト失敗 ($http_code)、リトライ中..."
  sleep $((i * 2))
done

​
冪等キーを使用しない場合の動作

  • 同じリクエストの繰り返し送信は 毎回実行され、リソースの重複作成につながる可能性があります。
  • 重要でない操作、またはビジネス層で重複排除を実装済みのシナリオでは、冪等キーを使用しなくてもかまいません。
  • GET リクエストには冪等キーが不要で、本質的に安全にリトライ可能です。