冪等性

なぜ重要か

ネットワークはリクエスト途中で失敗します。POST /v1/activations を実行して、レスポンスを受信する前に接続が切れた場合、アクティベーションが作成されたかどうかわかりません。素朴なリトライは二重課金につながる可能性があります。

Idempotency-Key ヘッダーはこれを解決します：リトライ時に同じキーを送信すれば、同じ結果が得られます。

使い方

論理操作ごとにUUIDを生成し、同じ操作のリトライごとに送信します：

KEY=$(uuidgen)
curl -X POST https://api.eveses.com/v1/activations \
  -H "Authorization: Bearer $EVESES_API_KEY" \
  -H "Idempotency-Key: $KEY" \
  -d '{"country":"ua", "service":"telegram"}'

同じ Idempotency-Key で同じ呼び出しを再実行すると、元のレスポンスが返ります——2回目のアクティベーションも、2回目の課金もありません。

TTL

キーは 24時間 記憶されます。その後スロットは解放され、同じキーを新規として再利用できます。

適用範囲

作成または課金する POST /v1/* のすべてのエンドポイント：アクティベーション、レンタル、入金、延長。読み取りエンドポイント（GET）はすでに冪等であり、ヘッダーを無視します。

競合

同じキーを異なるbodyで再利用すると、APIは409 idempotency_conflict を返します。リトライ時はbodyを同一に保つか、新しいキーを生成してください。

SDKの動作

公式SDKは各createコールに対して冪等性キーを自動生成し、自動リトライで再利用します。必要に応じて明示的なキーで上書きできます。