送金APIは「失敗5回連続」で切り替える――冪等キーと202の設計
Javaのサーバーが外部の送金APIを呼ぶ設計を考える。送金先の状態が「送金中」から「失敗」に変わったら、別の決済プロバイダへ送金を切り替える。切り替えの判断には「直近の連続失敗回数が5以上である」ことを使う。この設計で押さえる点は3つある。202 Acceptedで受けて冪等キーで二重送金を防ぐこと、失敗を「連続5回」で数えること、切り替えの判断と実行を分けることである。
失敗の通知をWebhookで受ける設計や、重複排除の考え方は、以前の記事でも扱った。決済履歴の重複排除と集計の記事では、FAILEDも「出現した」として記録する順序を書いた(決済履歴の重複排除と集計をJavaでO(n)で解く――FAILEDも「出現した」として記録する順序)。APIの制限側の数え方は、固定窓の境界バーストの記事で扱った(「60秒3回」のAPI制限は境界で2倍通る――固定窓のバーストとRedisの数え方)。
202 Acceptedは「受け取った」であって「送金した」ではない
送金要求のエンドポイントは POST /transfers とする。リクエストには冪等キー、金額、通貨、送金先の口座IDを含める。金額は 10000 が100.00円を表す整数の最小単位で送る。浮動小数点数は使わない。送金先は口座番号そのものではなくIDで指定し、機密情報をリクエストに載せない。
レスポンスは 202 Accepted で返す。201 Created ではない。202は「受け取って処理を始めた」という意味で、処理が終わったという意味ではない。RFC 9110の15.3.3節は、202のレスポンスを「意図的に非確定的(intentionally non-committal)」と書いている。処理はあとで拒否される可能性があり、同じリクエストに対する最終的な状態コードをあとから送る仕組みはHTTPにはない。だから202のレスポンスには、現在の状態の説明と、状態を確認できる場所へのポインタを含めるべきだとされている。
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.UUID;
public class TransferClient {
private final HttpClient http = HttpClient.newHttpClient();
private final String baseUrl;
public TransferClient(String baseUrl) {
this.baseUrl = baseUrl;
}
public HttpResponse<String> createTransfer(long amountMinorUnit, String currency,
String destinationAccountId) throws Exception {
// 冪等キーは最初の送信の前に作る。リトライでは同じキーを使い回す。
String idempotencyKey = UUID.randomUUID().toString();
String body = """
{"amount": %d, "currency": "%s", "destinationAccountId": "%s"}"""
.formatted(amountMinorUnit, currency, destinationAccountId);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(baseUrl + "/transfers"))
.header("Content-Type", "application/json")
.header("Idempotency-Key", idempotencyKey)
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
return http.send(request, HttpResponse.BodyHandlers.ofString());
}
}
202のレスポンスには transferId と status、送金先の状態を確認する GET /transfers/{transferId} のURLを入れる。状態は pending、processing、succeeded、failed、cancelled の5つで表す。状態確認のレスポンスには failureCode と failureCount、nextRetryAt も入れる。呼び出し側が「次に何をすべきか」をレスポンスだけで判断できるようにするためである。202を返したあとにクライアントが何も確認できない設計は、202を返していないのと同じである。
冪等キーはリトライの前に作る
送金はリトライが避けられない。ネットワークが切れれば、サーバー側で送金が終わったのか、始まってもいないのか、クライアントには分からない。同じ送金をもう一度送れば、二重送金になる。冪等キーはこの曖昧さを解消する仕組みである。クライアントが操作ごとに一意のキーを発行し、サーバーはそのキーで最初の結果を保存して、同じキーでの再送には保存した結果を返す。
StripeのAPI v1の冪等性仕様は、この挙動を具体的に定めている。キーはクライアントが生成するもので、UUID v4のような十分にランダムな文字列が推奨され、長さは最大255文字である。サーバーはエンドポイントの実行が始まったあとの最初のリクエストのステータスコードとボディを保存する。500エラーの結果も保存される。キーは少なくとも24時間は保持され、そのあとは削除されてよい。同じキーを別のパラメータで再利用すると、黙って再実行されるのではなく拒否される。GETとDELETEは定義上冪等なので、キーを送っても意味はない。
public record TransferRequest(
String idempotencyKey,
long amountMinorUnit,
String currency,
String destinationAccountId) {
}
検証では、冪等キーをキーにした台帳モデルをPythonに写して確かめた。同じキーでの再送は保存済みの結果が返り、送金処理が走った回数は1回のままだった。キーを変えて再送すると処理は2回走り、送金が2件になった。同じキーで金額だけ変えて再送すると拒否された。冪等キーは「送るたびに作り直すもの」ではなく「操作にひも付けて使い回すもの」である。リトライのたびに新しいキーを作る実装は、二重送金を防ぐ設計になっていない。
24時間という保持期間にも意味がある。Stripeの仕様では、未解決の操作のリトライは最初のリクエストから24時間以内に同じキーとパラメータでおこなうことになっている。24時間を過ぎても結果が分からない操作は、新しいキーで再送してはいけない。結果を照会して突き合わせる段階になる。冪等キーは万能ではなく、保持期間を過ぎた操作は別の運用で回収する設計が要る。
「連続5回」と「1時間に5回」は別の数え方
切り替えの判断は「直近の連続失敗回数が5以上」である。ここで「連続」と「1時間に5回」を取り違えると、切り替えのタイミングが変わる。両方は別の数え方で、食い違う場面がある。
| イベント列 | 連続失敗 | 1時間窓の失敗 | 切り替え(連続5回基準) |
|---|---|---|---|
| 失敗が40分以内に5回連続 | 5 | 5 | する |
| 失敗と成功が交互に5回(40分以内) | 1 | 5 | しない |
| 失敗が2時間かけて5回連続 | 5 | 3 | する |
| 4回失敗のあと成功 | 0 | 4 | しない |
2行目は、成功が間に入るたびに連続回数がリセットされるため、1時間に5回失敗していても切り替えない。3行目は逆で、失敗がゆっくり5回続いた場合、1時間の窓では3回しか数えられないが、連続では5回になるので切り替える。どちらが正しいかは、切り替えたい故障の姿で決まる。「プロバイダが死んでいる」ことを検知したいなら連続回数が合う。「負荷でたまに失敗する」ことを検知したいなら時間窓が合う。しきい値の数字だけ決めて、数え方を決めない設計は、切り替えの判断がぶれる。
この違いがあるため、切り替えの判断は「数字を出すAPI」と「切り替えるAPI」に分ける。GET /transfers/failure-stats?provider=p1&window=1h が consecutiveFailures と threshold、shouldSwitch を返し、切り替え自体は POST /transfers/{transferId}/switch-provider でおこなう。判断と実行を分けると、数字の出し方を変えても切り替えのAPIは変わらないし、切り替えの履歴に「誰が・なぜ切り替えたか」が残る。切り替えのボディには reason を必須にする。理由なしでは切り替えない。
public class ConsecutiveFailureCounter {
private int consecutiveFailures = 0;
private final int threshold;
public ConsecutiveFailureCounter(int threshold) {
this.threshold = threshold;
}
public void record(boolean succeeded) {
if (succeeded) {
consecutiveFailures = 0;
} else {
consecutiveFailures++;
}
}
public boolean shouldSwitch() {
return consecutiveFailures >= threshold;
}
public int consecutiveFailures() {
return consecutiveFailures;
}
}
失敗の通知はWebhookで受けるが、署名を見ないと偽物が通る
失敗をポーリングで拾う設計もできるが、送金先の状態が「送金中」から「失敗」に変わった瞬間を知るには、Webhookでpushしてもらう方が早い。POST /webhooks/transfers で、送金ID、状態、プロバイダ、失敗コード、発生時刻を受け取る。ただし署名を検証しないWebhookは、誰でも送金を「失敗した」ことにできる穴になる。Stripeのドキュメントは、署名を検証しないと攻撃者が偽のイベントを送って注文の発送や権限の付与を引き起こせると書いている。
Stripeの署名方式は、HMAC-SHA256で {タイムスタンプ}.{生のボディ} に署名する。ヘッダーには t= のタイムスタンプと v1= の署名が入る。検証の要点は4つある。検証する前にJSONとしてパースしないこと(生のボディを使うこと)、タイムスタンプが5分より古いものはリプレイとして拒否すること、比較は定数時間比較にすること、署名のバージョンはv1だけを受け入れることである。公式ライブラリがある言語ではライブラリを使うのが正しい。
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.security.InvalidKeyException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.HexFormat;
public class WebhookVerifier {
private static final long TOLERANCE_SECONDS = 300;
public static boolean verify(String secret, String header, String rawBody, long nowSeconds)
throws NoSuchAlgorithmException, InvalidKeyException {
String timestamp = null;
String signature = null;
for (String part : header.split(",")) {
String[] kv = part.split("=", 2);
if (kv.length == 2 && kv[0].equals("t")) {
timestamp = kv[1];
} else if (kv.length == 2 && kv[0].equals("v1")) {
signature = kv[1];
}
}
if (timestamp == null || signature == null) {
return false;
}
long t = Long.parseLong(timestamp);
if (Math.abs(nowSeconds - t) > TOLERANCE_SECONDS) {
return false;
}
String signedPayload = timestamp + "." + rawBody;
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] expected = mac.doFinal(signedPayload.getBytes(StandardCharsets.UTF_8));
byte[] received = HexFormat.of().parseHex(signature);
return MessageDigest.isEqual(expected, received);
}
}
検証では、署名が正しいボディは受理され、ボディを1文字でも改ざんすると拒否され、301秒前の署名は拒否され、299秒以内の到着は受理されることを確かめた。署名の検証は「送り主の確認」であって「順序の保証」ではない。Webhookのリトライは順序が保証されないため、重複したイベントは eventId で排除し、順序はシーケンス番号やタイムスタンプで管理する。2xxが返らない場合のリトライは指数バックオフで、最大24時間まで続けたあとはデッドレターに入れる。
切り替えの判断と実行を分ける
切り替えの処理は、判断する側と実行する側に分ける。失敗回数を数える failure-counter が連続失敗回数を数え、しきい値を超えたら provider-switcher が切り替えを判断し、実際の切り替えは transfer-worker がおこなう。判断と実行を分ける理由は、判断が間違っていても実行を止められることである。判断だけなら取り消せるが、送金を別プロバイダへ切り替えたあとでは取り消せない。
切り替え自体にも冪等キーを付ける。2つのワーカーが同時に5回目の失敗を見て、両方が切り替えを試みる場面があるからである。検証では、同じ切り替えキーでの2回の呼び出しは実行回数が1回だけになることを確かめた。切り替えのAPIに冪等キーがなければ、同じ送金が2回切り替えられ、履歴に2件の切り替えが残る。
状態遷移の履歴も残す。GET /transfers/{transferId}/events で、送金要求、プロバイダ選択、プロバイダ失敗、プロバイダ切り替え、成功、失敗のイベントを、eventId、type、occurredAt、provider、reason、actor と一緒に返す。送金中から失敗に変わった理由と、誰が(何が)切り替えたのかを、あとから追えるようにするためである。監査のための送金履歴はRDSに残し、送金状態と冪等キーと連続失敗回数はDynamoDBに置く。読み書きのパターンが違うデータを同じ場所に置くと、どちらかの都合で設計が歪む。
エラー設計では、409と422を使い分ける。完了済みやキャンセル済みの送金の切り替えは状態の競合なので409、プロバイダが利用不可で値は正しいが処理できない場合は422である。402は残高不足、429はレート制限、400はリクエストの形式の誤り、500は内部エラーに割り当てる。429については、以前の記事で固定窓の境界バーストを扱ったとおり、制限の数え方自体が設計の一部である。
壊れる場所
この設計で壊れる場所は、切り替えの瞬間に集まる。
- 切り替えの途中で送金が走る。 P1への送金が処理中のまま、切り替えの判断が出る。P1側で送金があとから成功し、P2側でも送金が走れば二重送金になる。処理中の送金は、切り替えの前に状態を確定させるか、切り替え後にP1側の結果を照会して突き合わせる必要がある。
- P2も失敗する。 切り替え先が死んでいれば、切り替えは故障の先送りにしかならない。切り替えの判断には、切り替え先の健全性も入れる。P2の連続失敗回数も数えておき、P2も5回連続で失敗しているなら切り替えない、という判断も要る。
- 失敗回数を数える側が死ぬ。 failure-counterが止まれば、失敗を数えられず切り替えが起きない。数える側の死活監視と、数え直しの手段(イベント履歴からの再計算)を用意する。イベント履歴が残っていれば、数え直しはできる。
- カウンタの更新が競合する。 2つのワーカーが同時に失敗を記録し、両方が「5回目だ」と読めば、切り替えが2回走る。カウンタの更新は条件付き書き込みにし、切り替えの実行自体にも冪等キーを付ける。検証で確かめたとおり、切り替えキーでの重複排除が最後の砦になる。
- Webhookが届かない。 署名の検証に失敗したイベント、リトライの上限を超えたイベントは、デッドレターに入る。デッドレターに入ったイベントを誰も見なければ、失敗の通知が消える。デッドレターの滞留数も監視対象に入れる。
検証環境
Javaコードはこの環境にJDKがなく、JVMで実行していない。構文は目視で確認した。ロジックは同じ内容をPython 3.12.3に写して検証した。検証スクリプトは verify-2026-11-16-morning-transfer-failover.py である。連続失敗と1時間窓の数え方の食い違い(6件のイベント列)、冪等キー台帳(同じキーでの再送は処理1回、キーを変えた再送は処理2回、別金額での再利用は拒否)、切り替えの二重実行防止(2ワーカーの同時切り替えでも実行1回)、Webhook署名検証(改ざんは拒否、301秒前は拒否、299秒以内は受理)をすべて確認した。金額の単位や状態の定義は、会話で学んだ内容に沿っている。Stripeの冪等性仕様とWebhook署名仕様、RFC 9110の202の定義は、2026年11月16日に公式ドキュメントと仕様書で確認した。
今後見るべきもの
- Stripeの冪等性仕様の変更。 API v1ではキーの保持は24時間以上だが、API v2では再送の挙動と保持期間が異なる。自分のAPIでどちらの挙動を採るかは、仕様として明記しておく。Stripeのドキュメントの更新を追う。
- 202のレスポンスに含めるもの。 RFC 9110は状態の説明と状態確認へのポインタを求めている。自分のAPIの202がそれを満たしているか、レスポンスの実物で確かめる。
- 連続失敗回数のしきい値と窓の決め方。 5回という数字は、プロバイダの平常時の失敗率と、切り替えのコストで決まる。平常時に5回連続で失敗する確率と、切り替えにかかる時間を見て、しきい値を見直す。
- 切り替えの実行回数と二重切り替えの件数。 切り替えの冪等キーの衝突や再送の回数を数える。切り替えが2回走った記録があれば、判断と実行の分離が崩れている合図である。
- Webhookの署名失敗数とデッドレターの滞留数。 署名失敗が増えれば、秘密鍵のローテーションか、送信側の仕様変更を疑う。デッドレターが滞留すれば、失敗の通知が届いていないことになる。
- 128信用金庫の障害の記事で扱った、振込だけ最後まで戻らなかった理由。 共同システムの障害では、送金の状態遷移と復旧の順序が問題になった(128の信用金庫が13時30分に止まり19時05分に復旧した――通信機器の故障と、振込だけ最後まで戻らなかった理由)。状態遷移の履歴を残す設計は、障害のあとで何が起きたかを追うためにも要る。
参考資料
- RFC 9110: HTTP Semantics, Section 15.3.3 (202 Accepted)
- Idempotent requests | Stripe API Reference
- Advanced error handling | Stripe Documentation
- Receive Stripe events in your webhook endpoint
- 決済履歴の重複排除と集計をJavaでO(n)で解く――FAILEDも「出現した」として記録する順序
- 「60秒3回」のAPI制限は境界で2倍通る――固定窓のバーストとRedisの数え方
- 128の信用金庫が13時30分に止まり19時05分に復旧した――通信機器の故障と、振込だけ最後まで戻らなかった理由