冪等性とリトライ

すべてのリアルタイム呼び出しには Idempotency-Key を付ける必要があります。これはレート制限への配慮ではなく、リトライを安全にするためのものです。サプライヤーに問い合わせた後にネットワークが失敗することがあります。キーがなければ、チェックが実行されたかを確かめる唯一の方法は、もう一度実行して二重に支払うことです。

ルール

再生成できる値を送信してください。UUID、注文 ID、または実行中の処理のハッシュなどです。サーバーはそれをアカウント単位にスコープするため、2人のユーザーが衝突することはありません。

同じキー	ペイロード	結果
新しいキー	任意	通常どおり実行され、課金されます
同じキー	同一	保存されたレスポンスが返されます。replayed=true。新たな課金はありません。
同じキー	異なる	409 idempotency_conflict — キーは最初に付与されたペイロードに紐づきます
同じキー	同一、最初の呼び出しがまだ実行中	Retry-After 付きの 409 request_in_progress

Idempotency-Key は 191 バイト に制限され、リプレイ記録はデフォルトで 30 日間 保持されます。

replayed と cached は別物

レスポンス内では似て見えますが、意味は異なります。

フィールド	場所	意味
replayed	トップレベル	この呼び出しはサプライヤーに到達していません — キーをリプレイしたのです。
cached	各結果の内部	このプロダクトの判定は結果キャッシュから提供されました。

リプレイされた呼び出しは、各エントリの cached 値を含め、元のレスポンスを再現します。どちらのフラグも課金額を変えません。リプレイで金額が動くことはなく、キャッシュヒットでもプロダクトの1チェックあたりの価格で課金されます。

ファクトとして保存されるのは確定した結果のみです。失敗した結果と unknown の結果はキャッシュされません。同じ識別子を同じプロダクトで後からチェックすると、決定的でない回答をリプレイするのではなく、サプライヤーに再度問い合わせます。

失敗後のリトライ

確認した内容	対処
タイムアウト、または HTTP 500	元のボディ を 元のキー で再送してください。結果は不確実であり、まさにこのケースのためにキーが存在します。
409 request_in_progress	Retry-After 待ってから、同じボディを同じキーで再送してください。
409 idempotency_conflict	そのキーはすでに別のペイロードに紐づいています。新しいキーを生成してください — ボディを編集して古いキーを再利用しないでください。
429 realtime_rate_limited	Retry-After 待ってください。何も送信されていないため、同じキーは未使用のままで安全に送信できます。
503 realtime_route_unavailable	何も送信されていません。後で同じキーでリトライしてください。

タイムアウト後に決してしてはならないのは、同じ処理を 新しい キーで送信することです。最初の呼び出しが実際に到達していた場合、そのチェックに対して二重に支払うことになります。

ここで発生するエラー

HTTP	code
400	idempotency_key_required — ヘッダーがありません
409	request_in_progress — 元の呼び出しがまだ実行中
409	idempotency_conflict — そのキーが最初に別のペイロードで使用された