共通の約束

すべての操作に共通する取り決めです。個別の操作の詳細は API リファレンスを参照してください。

エラー

失敗の応答は共通の封筒で返ります。code は次の 19 種類です。

VALIDATION_ERROR
INVALID_CURSOR
METHOD_NOT_ALLOWED
AUTHENTICATION_REQUIRED
INVALID_CREDENTIAL
FORBIDDEN
NOT_FOUND
CONFLICT
IDEMPOTENCY_KEY_REUSED
PRECONDITION_FAILED
PAYLOAD_TOO_LARGE
UNPROCESSABLE_ENTITY
RATE_LIMITED
SINGLE_PENDING
INTERNAL_ERROR
BAD_GATEWAY
SERVICE_UNAVAILABLE
GATEWAY_TIMEOUT
PRECONDITION_REQUIRED

一覧取得とページング

一覧は次のクエリ引数を受け取ります: limit cursor status q

続きは応答に含まれるカーソルを cursor へ渡して取得します。カーソルは不透明な文字列で、組み立てたり分解したりしないでください。古いカーソルや改変したカーソルは INVALID_CURSOR になります。

冪等性

状態を変える操作には Idempotency-Key ヘッダが必須です。同じキーで同じ内容を送り直すと、二重に実行されず最初の結果が返ります。同じキーで違う内容を送ると IDEMPOTENCY_KEY_REUSED になります。リトライではキーを変えないでください——変えると二重起票になります。

レート制限

上限に達すると RATE_LIMITED が返ります。応答のヘッダに従って待ってから再試行してください。待たずに再試行し続けると、回復が遅くなります。