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

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 は現在、アプリケーション層では 独自のレート制限機構を実装していません。リクエスト頻度はゲートウェイ層のグローバル保護ポリシーによって管理されます。

​
現在の状態

レイヤーレート制限ポリシー説明
API アプリケーション層なし429 Too Many Requests を能動的に返さない
ゲートウェイ層ありグローバル保護、異常トラフィックの衝撃を防止
API 層では明示的なレート制限がないとはいえ、無制限にリクエストを送信できるという意味ではありません。ゲートウェイ層は依然として異常トラフィック時にインターセプトを行い保護します。

​
ゲートウェイ層の保護

ゲートウェイ層は以下の保護機能を提供します。
  1. バーストトラフィック抑制 — 短時間内に大量のリクエストを送ると、一時的にインターセプトされる場合があります。
  2. 接続数制限 — 単一クライアントの同時接続数に上限があります。
  3. DDoS 防護 — 悪意のあるトラフィックを自動的に識別してブロックします。
ゲートウェイ保護がトリガーされると、以下を受け取る可能性があります。
  • HTTP 429 または 503 レスポンス
  • 接続が直接リセットされる（レスポンスボディなし）

​
推奨されるクライアント側戦略

明示的なレート制限がなくても、クライアント側で自律的な戦略を実装することを推奨します。

​
基本制限の推奨値

操作タイプ推奨頻度
読み取り操作（GET）50 回/秒 以下
書き込み操作（POST/PUT/DELETE）20 回/秒 以下
バッチトラバース（ページング取得）各リクエスト間隔 100ms 以上

​
指数バックオフリトライ

# バックオフリトライ付きリクエスト例 \
max_retries=3
retry_delay=1

for i in $(seq 1 $max_retries); do
  response=$(curl -s -w "\n%{http_code}" \
    https://openapi.qoder.sh/api/v1/cloud/agents \
    -H "Authorization: Bearer $QODER_PAT")

  http_code=$(echo "$response" | tail -1)

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

  # サーバーエラーまたはレート制限、待機後にリトライ
  echo "リクエスト失敗 ($http_code)、${retry_delay}s 後にリトライ... ($i/$max_retries)"
  sleep $retry_delay
  retry_delay=$((retry_delay * 2)) # 指数バックオフ
done

​
計画中のレート制限戦略

将来のバージョンでは、正式なレート制限機構が導入される予定です。以下が含まれることが期待されます。
機能期待される動作
レート制限レスポンスヘッダーX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset
レート制限ステータスコード429 Too Many Requests
レート制限粒度PAT / 組織 / エンドポイント別に制御
リトライヒントRetry-After レスポンスヘッダー
期待されるレスポンスヘッダー形式（計画中）: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1717200000
Retry-After: 30
クライアントコードに、429 ステータスコードと Retry-After ヘッダーの処理ロジックを予約しておくことを推奨します。これにより、将来レート制限がリリースされたときにシームレスに適応できます。

​
バッチ操作の推奨事項

大量の API 呼び出しが必要なシナリオでは: 
# 複数 Agent の詳細をバッチ取得（スロットリング付き） \
agent_ids=("agent_001" "agent_002" "agent_003" "agent_004" "agent_005")

for id in "${agent_ids[@]}"; do
  curl -s "https://openapi.qoder.sh/api/v1/cloud/agents/$id" \
    -H "Authorization: Bearer $QODER_PAT"
  # リクエスト間隔 200ms、ゲートウェイ保護のトリガーを回避
  sleep 0.2
done

​
モニタリングの推奨事項

  • 各リクエストのレスポンス時間を記録します。レスポンスが遅くなることはゲートウェイ制限に近づいているシグナルである可能性があります。
  • 5xx エラー率に注目します。急増は保護がトリガーされたことを示している可能性があります。
  • サーキットブレーカーパターンを実装し、連続失敗時にリクエストを一時停止します。