Skip to main content

エラーフォーマット

すべてのエラーレスポンスは一貫した構造に従います。

errors 配列の読み方

errors 配列は根本原因からトップレベルの呼び出し元の順に並んでいます。
  • errors[0] — 障害の根本原因(デバッグに最も有用)
  • errors[n] — エラーを表面化させたトップレベルの呼び出し元
ほとんどの場合、errors[0].message を確認するだけで対処可能なエラー説明を取得できます。

HTTP ステータスコード


エラーの layer フィールド

各エラーには、システムのどの部分がエラーを生成したかを示す layer 文字列が含まれます。デバッグ時に根本原因を特定するために、layer 値を message と合わせて使用してください。

よくあるエラーシナリオ

認証エラー (401)

解決方法:
  • Merchant ID と秘密鍵が正しいことを確認してください
  • SDK が有効な認証情報で初期化されていることを確認してください
  • 秘密鍵が登録済みの公開鍵と一致することを確認してください

バリデーションエラー (400)

解決方法:
  • 必須フィールドが存在することを確認してください
  • フィールド値のフォーマットと制約を確認してください
  • 金額が表示フォーマット文字列(例:"29.00")であることを確認してください

権限エラー (403)

解決方法:
  • API Key が必要な権限を持っていることを確認してください
  • ユーザーが正しいストアに所属していることを確認してください

冪等性コンフリクト (409)

解決方法:
  • 元のリクエストの完了を待ってください
  • 新しいリクエストには別の X-Idempotency-Key を使用してください

コードでのエラー処理

TypeScript SDK


リトライ戦略

以下のステータスコードに対して指数バックオフでリトライしてください。
  • 429 — レート制限(Retry-After ヘッダーがある場合はそれに従ってください)
  • 500 — 内部サーバーエラー
  • 502 — Bad Gateway
400401403404 エラーはリトライしないでください。これらはリクエスト自体の修正が必要な問題を示しています。

安全なリトライのための冪等性

X-Idempotency-Key ヘッダーを使用して、重複を作成せずに書き込み操作を安全にリトライできます。
  • 冪等キーは 24 時間 キャッシュされます
  • 同じキーを送信すると、キャッシュされたレスポンスが返されます
  • 元のリクエストがまだ処理中の場合は、409 Conflict が返されます

冪等キーの要件

キーはリクエストのキャッシュ識別子そのものであるため、一意性が最も重要な要件です。方法は 2 つあります。
  1. SDK に生成させる(推奨)。 TypeScript SDK は merchantId + パス + ボディ の決定的なハッシュとしてキーを導出するため、構造上リクエストごとに一意になります。
  2. 自分で構築する。 キーに merchantId と UUID などの高エントロピーな要素を含めてください。例:MER_2aUyqjCzEIiEcYMKj7TZtw-8f14e45f-ea8c-4b0a-9f7d-3b2c1d0e5a67
order-abc-123 のような短く推測しやすいキーは、別のリクエストが既に使用しているキーと一致する可能性があります。その場合、返されるのは自分の呼び出しの結果ではなく、そのリクエストのキャッシュされたレスポンスです。