エラーフォーマット
すべてのエラーレスポンスは一貫した構造に従います。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
400、401、403、404 エラーはリトライしないでください。これらはリクエスト自体の修正が必要な問題を示しています。安全なリトライのための冪等性
X-Idempotency-Key ヘッダーを使用して、重複を作成せずに書き込み操作を安全にリトライできます。
- 冪等キーは 24 時間 キャッシュされます
- 同じキーを送信すると、キャッシュされたレスポンスが返されます
- 元のリクエストがまだ処理中の場合は、
409 Conflictが返されます
冪等キーの要件
キーはリクエストのキャッシュ識別子そのものであるため、一意性が最も重要な要件です。方法は 2 つあります。
- SDK に生成させる(推奨)。 TypeScript SDK は
merchantId+ パス + ボディ の決定的なハッシュとしてキーを導出するため、構造上リクエストごとに一意になります。 - 自分で構築する。 キーに
merchantIdと UUID などの高エントロピーな要素を含めてください。例:MER_2aUyqjCzEIiEcYMKj7TZtw-8f14e45f-ea8c-4b0a-9f7d-3b2c1d0e5a67
order-abc-123 のような短く推測しやすいキーは、別のリクエストが既に使用しているキーと一致する可能性があります。その場合、返されるのは自分の呼び出しの結果ではなく、そのリクエストのキャッシュされたレスポンスです。