データ API を導入する技術的な手順は短いものです。キーを作り、ドキュメント通りにリクエストを送り、ステータスコードを確認する。クイックスタートと認証がすでに扱っています。
費用がかかるのはその前の五つの決定です。共通点は、今なら安く決められ、動き始めてからでは変更が痛いことです。
決定 1：呼び出し量をどう見積もるか
この数字が購入するコールパックを決め、残る四つの決定の厳しさも決めます。
最も多い誤差は「レポート一本＝一回の呼び出し」と数えることです。実際には競合週報一本で ASIN 20 件 × 項目 3 種 × 週 1 回 ＝ 60 回、さらに比較用に 12 か月分の履歴を取るなら初回は数百回になります。
対象数 × 項目種別数 × 頻度で見積もり、初回のバックフィルは別枠の一時費用として計上してください。初回と定常運用は一桁違うことが珍しくなく、定常だけで見積もると初日に予算を超えます。
決定 2：どの項目を保存し、どれを都度取得するか
判断基準は一つだけ、その項目がどれくらいの頻度で変わるかです。
| 変化の速さ | 代表的な項目 | 扱い |
|---|---|---|
| ほぼ変わらない | ASIN、ブランド、カテゴリ、発売日 | 保存し、欠けている時だけ取得 |
| 日単位 | BSR、評価数、販売数の推定 | 保存＋定期更新 |
| 常時変わる | 価格、クーポン、在庫状況 | 都度取得。一晩キャッシュしない |
どちらに振り切っても無駄が出ます。何も保存しなければ変わらないデータに繰り返し払い、全部保存すれば古い価格で判断することになります。
「変わらない項目のテーブル」と「タイムスタンプ付きの履歴テーブル」に最初から分けるほうが、後から分離するよりはるかに楽です。タイムスタンプの無い数値は、三か月後にまだ使えるかどうかを判断できません。
決定 3：リトライは分類する。一律にしない
最も書き間違えられる箇所です。失敗は一種類ではないので、リトライも一つの分岐で済ませてはいけません。
| ステータス | 代表的なエラーコード | リトライの意味 | 対応 |
|---|---|---|---|
400 | VALIDATION_ERROR | 無い | 内容を変えずに再送しても同じく失敗します |
401 | INVALID_API_KEY、API_KEY_EXPIRED | 無い | キーを差し替える。退避再送はしない |
402 | INSUFFICIENT_CREDITS | 無い | 残高切れ。何回送っても成功しません |
403 | ENDPOINT_NOT_INCLUDED | 無い | プランにその API が含まれていません |
413 | — | 無い | ボディが 64 KB 超。分割してください |
429 | RATE_LIMIT_EXCEEDED、CONCURRENCY_LIMIT_EXCEEDED | 有る | Retry-After に従って退避 |
503、504 | SERVICE_BUSY、SERVICE_TIMEOUT | 有る | 指数退避＋ランダムな揺らぎ |
402 と 429 は似ていますが別の問題です。 429 は「今は速すぎる、少し待て」で、退避すれば通ります。402 は残高が尽きた状態で、必要なのはアラートと入金の導線であってリトライループではありません。同じ catch に入れると、残高が切れた日にジョブが静かに空回りします。
429 の中の二つのエラーコードも別物です。RATE_LIMIT_EXCEEDED は毎分のリクエスト数超過、CONCURRENCY_LIMIT_EXCEEDED は同時実行数の超過です。前者は頻度を落として解決し、後者は並列数を落として解決します。頻度を落としても並列数は下がりません。
そのためのレスポンスヘッダーが三つあります。
| ヘッダー | 意味 |
|---|---|
X-RateLimit-Limit | 現在の分ウィンドウで許可されるリクエスト数 |
X-RateLimit-Remaining | 現在のウィンドウの残りリクエスト数 |
X-RateLimit-Reset | ウィンドウのリセット時刻、Unix 秒 |
429 を待ってから反応しないでください。X-RateLimit-Remaining が閾値を下回った時点で自分から減速するほうが、制限されてから退避するより処理量が出ます。
失敗したリクエストが残高を消費するかどうかは、推測しないでください。ログイン済みのアカウントは利用状況ページでリクエストのメタデータを確認でき、マスキングされたボディとレスポンスは 7 日間保持されます。公開前に意図的に失敗させ、呼び出し明細で照合するのが確実です。
エラーコードとレート制限ステータスコード表、エラーコード一覧、レート制限ヘッダー、呼び出し明細の保持期間決定 4：並列数はアカウント単位の予算であって、ジョブ単位の設定ではない
最も直感に反し、規模を拡大した時に効いてくる規則です。
RPM、並列数、Credits はアカウント単位で集計され、API キーを複数作っても追加の枠は得られません。
「ジョブごとに専用キーを配れば独立して動く」と考えがちですが、そうはなりません。定時ジョブ三本がそれぞれ 10 本の接続を開けば、アカウントから見れば同時 30 本で、先に走ったものが他を CONCURRENCY_LIMIT_EXCEEDED に追いやります。
したがって並列制御は、ジョブごとではなく全体で共有する一つのリミッターとして設計します。
- すべての呼び出しを一つのクライアントラッパー経由にし、リミッターは業務コードではなくラッパー内に置く
- ジョブに優先度を付ける。リアルタイムの照会は夜間のバックフィルより優先
- バックフィルには明示的に速度制限をかける。急がない一方で、枠を食い潰しやすいのはこちらです
もう一つ、先に知っておくべき上限があります。リクエストボディが 64 KB を超えると 413 が返ります。 一括系の API に ASIN のリストを渡す場合、この上限が 1 バッチの最大件数を決めます。本番で気づくのではなく、分割ロジックに書き込んでおいてください。
決定 5：チームでのキー管理
枠がもともとアカウント共有である以上、キーを増やす目的は枠ではありません。本当の価値は帰属と個別失効の二つです。
人ではなく用途で分けます。
prod-api、cron-backfill、dev-localのように分ければ、問題が起きた時に呼び出し明細からどの経路かを特定できます- ある経路で事故が起きたら、そのキーだけ止めれば他は動き続けます
- 退職者が出た時に洗うのは「その人が触れたキー」であって、アカウント全体ではありません
守るべき三点：キーはサーバー側の環境変数だけに置く、リポジトリに入れない、フロントエンドのコードに入れない。ブラウザからデータが必要な場面は、自社のバックエンド経由にしてください。
五つに共通すること
いずれも技術的な難問ではなく、元に戻す費用が非対称な選択です。呼び出し量を読み違えれば初月に分かり、キャッシュの切り分けを誤れば数字が合わなくなった時に分かり、リトライを一本にすれば残高が尽きた日に分かり、並列数をジョブ単位にすれば三本目のジョブで分かり、キーを人単位で配れば最初の退職で分かります。
最初のリクエストを書く前に 30 分かけてこの五つを決めておくほうが、後から戻ってくるより安上がりです。
次に API を選ぶ段階では、Amazon データ API 完全ガイドが 46 の API を業務シーン別に分解しています。そもそもサードパーティ API の道でよいかを判断中なら、Amazon データ API の選び方が先です。
よくある質問
API キーを増やせば上限は上がりますか。 上がりません。RPM、並列数、Credits はすべてアカウント単位で集計されます。複数キーの価値は帰属と個別失効であって、枠ではありません。
429 の後はどれくらい待つべきですか。
Retry-After があればそれに従ってください。無い場合は指数退避にランダムな揺らぎを加え、複数のジョブが同時刻に再送しないようにします。
失敗したリクエストが残高を消費するかはどう確認しますか。 利用状況ページの呼び出し明細で確認します。マスキング済みのメタデータは 7 日間保持されるので、公開前に一度失敗させて読み返してください。
一括リクエストには最大何件入りますか。 一律の数はなく、ボディの 64 KB 上限で決まります。実際のパラメータ長で一度測り、分割ロジックに余裕を持たせてください。