エラーレスポンスの構造

{
  "error": {
    "code": "invalid_parameter",
    "message": "store_id is required",
    "param": "store_id",
    "request_id": "req_01HV6N..."
  }
}

request_id はサポート問い合わせ時に必須です。エラーログに必ず含めてください。

HTTPステータスコード一覧

主なエラーコード

リトライ指針

リトライしてよい条件

• HTTPステータスが 429 または 5xx
• ネットワークタイムアウト・接続エラー
• POSTの場合はIdempotency-Key を必ず設定（重複作成を防ぐため）

リトライ間隔（指数バックオフ＋ジッター）

function retryDelay(attempt) {
  // 1, 2, 4, 8, 16秒（最大32秒）
  const base = Math.min(Math.pow(2, attempt), 32);
  // ±25%のジッターで集中アクセスを避ける
  const jitter = base * (Math.random() * 0.5 - 0.25);
  return (base + jitter) * 1000;
}

最大リトライ回数

• 通常API：最大5回
• バッチ処理：最大10回
• ユーザー操作起因：最大2回（待たせすぎない）

429の場合は Retry-After ヘッダーを優先

HTTP/1.1 429 Too Many Requests
Retry-After: 30

→ 30秒待ってから再試行

リトライしてはいけないケース

• 4xx（429除く）：リクエスト自体に問題があるため、何度試しても同じ
• POST/PUTで Idempotency-Key を付けていない場合：重複作成のリスク

関連ガイド

• リクエストとレスポンスの基本
• レート制限とスロットリング
• 開発者ヘルプトップへ戻る