エラーと利用制限

エラーの形式

エラーは共通のレスポンス形式で返されます。ドキュメントの言語を切り替えても、API のフィールド名やエラーメッセージは変わりません。

{
  "request_id": "8fb43e59-4ff9-4dc8-a4b7-2ed164e45ab8",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more request fields are invalid.",
    "details": [
      {
        "path": "asin",
        "message": "Must be a valid 10-character ASIN"
      }
    ]
  }
}

request_id はリクエストの識別子です。プログラムで処理を分岐する場合は error.code、説明を確認する場合は error.message を使用します。フィールドごとの検証情報がある場合のみ details が含まれます。この例では details[].path が asin を示しているため、その値を修正してから再送します。

HTTP ステータスコード

主なエラーコードは INVALID_JSON、VALIDATION_ERROR、API_KEY_REQUIRED、INVALID_API_KEY、API_KEY_EXPIRED、SUBSCRIPTION_REQUIRED、SUBSCRIPTION_INACTIVE、ENDPOINT_NOT_INCLUDED、RATE_LIMIT_EXCEEDED、CONCURRENCY_LIMIT_EXCEEDED、INSUFFICIENT_CREDITS、USAGE_LIMIT_EXCEEDED、SERVICE_BUSY、SERVICE_TIMEOUT、SERVICE_UNAVAILABLE です。

直接利用するユーザーの毎分リクエスト数、同時実行数、クレジットはアカウント単位で管理されます。API キーを追加しても上限は増えません。

利用制限に関するヘッダー

レスポンスには次のヘッダーが含まれる場合があります。すべてのレスポンスに含まれるとは限りません。

再試行の方針

429、503、504 では Retry-After に従い、待機時間を指数的に増やしながら、少しランダムな待機時間を加えて再試行してください。試行回数に上限を設定し、各試行の request_id を記録します。失敗が続く場合は再試行を止め、サービスの状態を確認するかサポートへお問い合わせください。

検証エラーや認証エラーは、リクエストを修正するまで自動で再送しないでください。402 ではクレジット、403 ではアクセス権限の確認が必要です。再試行は別のリクエストになります。クライアント側のタイムアウトだけを根拠に、前のリクエストが失敗したと判断しないでください。

利用履歴と調査

ログイン済みのユーザーは、利用履歴でリクエストのメタデータを確認できます。機密情報を除去したリクエスト本文と、最大 20 KB のレスポンス内容は 7 日間保存されます。シークレットや個人情報のフィールドは保存前にマスクされるため、履歴にレスポンス全体が表示されるとは限りません。

サポートには request_id、エンドポイント、発生時刻、エラーコードを伝えてください。API キーや認証ヘッダーは送らないでください。認証とはじめにも参照できます。