エラーと復旧

安定したエラーコードに基づき、修正、待機、再試行を判断します。

対処方法

人向けの error.message ではなく、HTTP ステータスと error.code で処理を分岐してください。
401 は有効な認証、403 はアクセス権またはプランの変更、409 は競合する操作やリソースバージョンの確認が必要です。

アクセス拒否と再試行

401: 401は必ずしもトークンの期限切れを意味しません。期限切れの場合は新しいトークンを取得し、読み取りを最大1回だけ再試行してください。トークン取得で401が返る場合は、キーを確認して自動試行を停止してください。
403: 403の場合は権限、IP制限、プランを確認してください。新しいトークンを取得しても、取り消されたアクセス権は復元されません。

認証

再試行方針

一時的な障害には、回数を制限し、待機時間を増やしながらランダムな遅延を加えて再試行します。
Retry-After があれば従ってください。
書き込みがタイムアウトすると結果が不明な場合があります。
同じ論理操作を再試行するときは、元の Idempotency-Key と変更していないリクエストを維持します。
以下の一覧に公開される全エラーコードを説明しています。

安全な書き込み

レート制限

422 / 409

価格について、通貨の形式または金額の精度が無効な場合は 422 request.validation_failed が返されます。
有効な通貨コードでも、選択した価格表の通貨と異なる場合は 409 resource.version_conflict が返されます。
再試行する前にコンテキストとバージョンを確認してください。

エラー一覧

400request.malformedリクエストを解析できません。

対処方法: JSON 構文、URL エンコード、リクエスト構造を確認してください。
再試行方針: リクエストを修正してから再試行します。

JSON

{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsAPI キーまたはアクセストークンが無効、期限切れ、または失効済みです。

対処方法: ストアの URL と認証情報を確認し、有効な API キーで新しいトークンを取得してください。
再試行方針: 認証を修正してから再試行します。無効なトークンで繰り返し要求しないでください。

JSON

{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.required必要な Authorization ヘッダーがないか、認証方式が誤っています。

対処方法: トークン要求には ApiKey、リソース操作には Bearer を使ってください。
再試行方針: 正しいヘッダーを指定してから再試行します。

JSON

{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverified信頼できるクライアント IP アドレスを確認できませんでした。

対処方法: ストア運用者に受信経路の確認を依頼してください。転送ヘッダーを自分で挿入しないでください。
再試行方針: 信頼できる接続経路が復旧してから再試行します。

JSON

{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowed送信元 IP アドレスがキーの許可リストに含まれていません。

対処方法: 許可された送信元を使うか、権限のある管理者にキーの IP リスト編集を依頼してください。
再試行方針: アドレスが許可されてから再試行します。

JSON

{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_deniedキーに、この操作で必要な有効な権限がありません。

対処方法: 操作の必須権限と条件付き権限、キーの付与権限、発行者のアクセス権を確認してください。
再試行方針: 権限のある管理者が必要なアクセスを付与してから再試行します。

JSON

{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabledこのストアの API アクセスは無効です。

対処方法: ストア所有者に現在のプランと API の利用可否を確認してもらってください。
再試行方針: API アクセスが有効になるまで再試行しないでください。

JSON

{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceeded変更すると現在のプランの上限を超えます。

対処方法: 対象リソースの上限を確認し、変更内容またはプランを調整してください。
再試行方針: 上限の問題を解消してから再試行します。リクエストを変更する場合は新しい冪等キーを使います。

JSON

{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabled現在のプランにはこの操作が含まれていません。

対処方法: 操作に記載された最低プランを確認してください。
再試行方針: プランが操作を許可し、キーに必要な権限がある状態で再試行します。

JSON

{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedプランの制限により、このリソースがブロックされています。

対処方法: 所有者に対象リソースのプラン制限を解消してもらってください。
再試行方針: ブロックが続いている間は同じリクエストを繰り返さないでください。

JSON

{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundリソースが存在しない、削除済み、または指定識別子で利用できません。

対処方法: ストア、リソースのパス、識別子を確認してください。このストアから返された識別子を使います。
再試行方針: 対象を修正するか、存在を確認してから再試行します。

JSON

{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedこのエンドポイントは指定した HTTP メソッドに対応していません。

対処方法: 文書化されたメソッドを使ってください。Allow ヘッダーに対応メソッドが示されます。
再試行方針: 非対応のメソッドを再試行しないでください。

JSON

{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reusedこの冪等キーは別のリクエストに使われています。

対処方法: 元の操作を確認してください。意図的に新しい論理操作を行う場合だけ、新しいキーを使います。
再試行方針: 競合したキーで変更済みの内容を再送しないでください。

JSON

{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_exists一意であるべき値が既存のリソースと競合しています。

対処方法: 既存のリソースを取得し、それを使うか別の一意な値を選ぶか判断してください。
再試行方針: 同じ競合する作成処理を繰り返さないでください。

JSON

{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_use他のリソースがまだこのリソースに依存しています。

対処方法: 依存関係を確認し、削除前に対応する操作で解除または変更してください。
再試行方針: 依存関係を解消してから再試行します。

JSON

{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflict現在の業務状態ではこの変更を実行できません。

対処方法: 現在の状態を取得し、有効な業務上の状態遷移を選んでください。
再試行方針: 競合する変更を自動で強制したり、繰り返し送信したりしないでください。

JSON

{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflict取得したバージョンの後に、別の書き込みがリソースを変更しました。

対処方法: 最新状態を取得し、変更を調整して、新しい expected_version を送信してください。
再試行方針: 修正後の操作には新しい冪等キーを使い、確認せず上書きしないでください。

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largeリクエストがサイズ上限を超えています。

対処方法: 内容を減らすか、対応する個別の操作に分割してください。
再試行方針: それぞれの冪等キーを使い、小さく有効な操作として再試行します。

JSON

{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_typeメディアタイプまたはコンテンツのエンコードに対応していません。

対処方法: JSON 書き込みには Content-Type: application/json と、対応する非圧縮の本文を使用してください。
再試行方針: メディアタイプまたはエンコードを修正してから再試行します。

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failed1つ以上のフィールドまたはパラメーターが検証に失敗しました。

対処方法: error.fields を確認し、必須フィールド、null の可否、識別子、許可された値を確認してください。
再試行方針: 修正したリクエストを再送します。変更した書き込みは新しい論理操作です。

JSON

{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullAPIの短い待機キューが満杯です。リクエストの実行は開始されていません。

対処方法: リクエストをキューに入れ、Retry-After レスポンスヘッダーに従ってください。
再試行方針: Retry-After の秒数以上待ち、ランダムな遅延を加えます。書き込みの再試行では元のキーと内容を維持します。

JSON

{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutAPIキューの待機時間が終了しました。リクエストの実行は開始されていません。

対処方法: リクエストをキューに入れ、Retry-After レスポンスヘッダーに従ってください。
再試行方針: Retry-After の秒数以上待ち、ランダムな遅延を加えます。書き込みの再試行では元のキーと内容を維持します。

JSON

{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceededリクエスト頻度が適用上限を超えています。

対処方法: リクエストをキューに入れ、Retry-After レスポンスヘッダーに従ってください。
再試行方針: Retry-After の秒数以上待ち、ランダムな遅延を加えます。書き込みの再試行では元のキーと内容を維持します。

JSON

{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.error予期しないサービスエラーが発生しました。

対処方法: リクエスト識別子を記録し、続く場合は運用者に連絡してください。ログに認証情報を含めないでください。
再試行方針: 回数を制限したバックオフを使います。書き込みでは元の冪等キーと変更していない内容を維持します。

JSON

{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseゲートウェイが有効な API レスポンスを受信できませんでした。

対処方法: リクエスト識別子を保存してください。失敗レスポンスでも書き込みが未実行とは限りません。
再試行方針: 回数を制限したバックオフを使います。同じ論理書き込みでは元の Idempotency-Key と内容を維持してください。

JSON

{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableAPI が一時的にリクエストを処理できません。

対処方法: Retry-After があれば従い、障害が続く場合はリクエスト識別子を保存してください。
再試行方針: 回数を制限しランダムな遅延を加えたバックオフを使います。同じ書き込みの再試行ではキーと内容を維持します。

JSON

{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutゲートウェイが API の応答待ちでタイムアウトしました。

対処方法: リクエスト識別子を保存し、書き込み結果は不明として扱ってください。
再試行方針: 回数を制限したバックオフを使い、書き込みでは元の冪等キーと変更していない内容を再利用します。

JSON

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}