エラーコードとリトライ指針

API エラーコードリトライ HTTPステータス

レシートローラーのAPIが失敗したときに返すステータスコードとレスポンス本文の形、どのエラーを送り直してよいかをまとめます。エラー本文は全エンドポイント共通の形ではなく、ほとんどは {"error": "..."} の簡単なJSONで、401 と 403 は本文なしで返ります。判定はまずステータスコードで行い、本文は原因の確認に使ってください。

エラー本文の形

多くのエラーは error に短い説明やコードが入ったJSONです。エンドポイントによって message・error_description・reason などの項目が加わります。
JSONの書式誤りや、数値の項目に数値以外を送ったときの 400 は、errors に項目ごとの理由が入った本文です。
401 と 403 は本文なしで返ります。
サーバー内部の予期しないエラーは 500 と {"error": "an unexpected error occurred"} です。

{ "error": "product not found in this business account" }

{ "error": "slot_unavailable", "reason": "...", "message": "..." }

共通のエラーコード一覧や、問い合わせ用のリクエストIDの項目はありません。

ステータスコード

コード	意味	送り直し
`200`	成功。作成の多くも `200` です（例：商品の作成）	―
`201`	一部の作成エンドポイントでの作成成功（例：店舗の投稿）	―
`204`	成功（本文なし）。削除などで返ります	―
`400`	必須項目の不足、値や形式の誤り	しない（リクエストを直す）
`401`	トークンがない、無効、期限切れ	トークンを更新してから1回
`402`	ビジネスアカウントのプランにその機能が含まれていない（例：Googleビジネスプロフィール）	しない
`403`	スコープ不足、`organizationId` がトークンと違う、メンバーでない、ロールが足りない	しない
`404`	対象がビジネスアカウントに存在しない	しない
`409`	状態の競合（例：クーポンコードが使用中、予約枠が埋まっている）	しない（状態を読み直して判断する）
`429`	一部のエンドポイントでのリクエスト数超過	待ってから送り直す（レート制限とスロットリング）
`500`	サーバー内部の予期しないエラー	間隔を広げながら数回
`502` / `503`	外部サービスの失敗や一時的な混雑（例：回数券の消化が同時に重なった）	間隔を広げながら数回

エンドポイントごとに返りうるステータスは APIリファレンスに載っています。

トークンエンドポイントのエラー

POST /api/v1/auth/token は OAuth の形式でエラーを返します。

ステータス	`error`	原因
`400`	`invalid_request`	本文が読めない、`code` や `refresh_token` がない
`400`	`unsupported_grant_type`	`grant_type` が対応していない値
`401`	`invalid_grant`、`invalid_client` など	コードやリフレッシュトークンが無効、クライアントの認証に失敗。`error_description` に詳細が入ります

リフレッシュトークンでの更新が 401 になった場合は、送り直さず、利用者にもう一度認可してもらってください。

送り直しの方針

送り直してよいのは 429、5xx、タイムアウト、接続エラーです。5xx では1秒・2秒・4秒…と間隔を倍にし、ゆらぎ（ジッター）を加えて、数回で打ち切ります。
429 は Retry-After があればその秒数、なければ1分ほど待ちます。
401 を除く 4xx は、同じリクエストを何度送っても同じ結果です。
共通の Idempotency-Key ヘッダーはありません。作成の POST をタイムアウト後に送り直すと二重に作成されることがあるため、送り直す前に作成済みかどうかを確認してください。
回数券の消化・取り消し（POST /api/v1/reservations/passes/{passId}/redeem・.../unredeem）と勤怠の打刻（POST /api/v1/stores/{storeId}/timecards/punch）は、本文の idempotencyKey で重複を防げます。同じキーで送り直すと、処理済みの結果が "replayed": true 付きで返り、二重には処理されません。

エラーコードとリトライ指針

エラー本文の形

ステータスコード

トークンエンドポイントのエラー

送り直しの方針

関連情報