HTTP 424 Failed Dependency はいつ使用すべきか、またリトライに対して安全な API コントラクトをどのように設計するか？

シナリオ

バッチ API が注文の検証、在庫の確保、および注文の作成を行います。在庫確保が失敗した場合、注文作成は決して実行されません。面接官は、エラーレスポンスを設計し、HTTP 424 が適切であるかどうかを論理的に説明することを求めています。

この質問でテストされること

標準化された HTTP セマンティクスとチーム固有の規約の区別。
依存関係グラフにおける部分完了、スキップされた処理、および結果不明の状態の表現。
冪等性、リトライ条件、およびエラー詳細を単一のコントラクトとして設計する能力。

模範解答

424 の適用境界

424 (Failed Dependency) は WebDAV RFC 4918 で定義されています。別の操作が失敗したためにメソッドを完了できなかったことを意味します。これは、すべてのダウンストリームサービスエラーに対する汎用的なエイリアスではありません。WebDAV 以外の API で 424 を採用することも可能ですが、そのパブリックコントラクトにおいて意味、クライアントの動作、および互換性の期待値を定義する必要があります。

ステータスコードの選択

412 Precondition Failed: If-Match などのリクエストの前提条件が満たされなかった。
409 Conflict: 在庫バージョンの変更など、リクエストが現在のリソース状態と競合している。
424 Failed Dependency: このステップは同一リクエストまたはワークフロー内の失敗したステップに明示的に依存しているため、実行されなかった。
5xx: リクエストの関係性がブロックされたステップを説明しているのではなく、サービス障害が原因でサーバーがリクエストを完了できなかった。

依存関係の 500 を機械的に 424 にマッピングしないでください。まず、このワークフロー内のステップがブロックされたかどうか、およびその事実に基づいてクライアントが別の対応を取れるかどうかを判断してください。

レスポンスボディとステートマシン

安定した type、title、status、detail に加え、blockedBy、operationId、retryable、completedSteps などの拡張フィールドを備えた RFC 9457 Problem Details を使用します。ビジネス拡張はコントラクトの一部であり、バージョニングが必要です。

json

{
  "type": "https://api.example.com/problems/failed-dependency",
  "title": "Order creation was blocked",
  "status": 424,
  "detail": "Inventory reservation failed",
  "blockedBy": "reserve-inventory",
  "operationId": "op_123",
  "retryable": true,
  "completedSteps": ["validate-order"]
}

リトライと結果不明の状態

自動リトライは、retryable=true かつ同一の冪等性キーが使用されている場合にのみ行います。在庫確保がコミットされた後に接続が切断された場合、サーバー側の結果が不明であるため、クライアントはタイムアウトを 424 と見なすことはできません。operationId で照会する必要があります。完了した副作用は、2 回目のリクエストを新規と見せかけることではロールバックできません。ビジネス要件に応じて補償トランザクションを提供してください。

よくある間違い

424 をすべてのマイクロサービスエラーに対する汎用ステータスとして扱うこと。
安定したエラータイプや操作 ID を含めず、散文のテキストのみを返すこと。
すべての 424 をリトライし、重複した在庫確保や注文を発生させること。
障害を 424 の背後に隠蔽し、監視システムがワークフローのブロックとプラットフォーム障害を切り分けられなくなること。

フォローアップの質問

バッチリクエストは部分的に成功できますか？

はい。ただし、アイテムごとのステータス、冪等性情報、および依存関係の詳細を返してください。バッチの HTTP ステータスは集約された結果を表すものであり、個別アイテムの結果を置き換えることはできません。ビジネス上アトミック性が求められる場合は、すべての変更がロールバックされるのか、あるいは何もコミットされないのかを明記してください。

409 が 424 よりも適切なのはどのような場合ですか？

リソースバージョンや在庫状態の競合は現在のリソースの問題であり、通常は 409 が適しています。同一ワークフロー内の別のステップが失敗したために現在のステップがスキップされた場合は、424 を使用してください。

依存関係が 503 を返した場合はどうなりますか？

現在のステップがブロックされており、コントラクトがそれをワークフローの依存関係の失敗として扱う場合、424 の詳細情報に根本原因を含めることができます。サービス全体が利用できない場合は、503 を返し、Retry-After などのサービスレベルのシグナルを使用します。監視およびクライアントポリシーにおいて、これらのケースを区別する必要があります。

コントラクトはどのようにテストしますか？

依存関係の成功、拒否、タイムアウト、コミット後の接続切断、重複した冪等性キー、部分完了、および復旧のための問い合わせを網羅します。HTTP 番号だけでなく、ステータス、Problem Details フィールド、最終状態、および副作用の回数をアサートしてください。

採点ルーブリック

合格（Passing）

424 の WebDAV における起源を正確に説明し、409、412、5xx の境界を明確にし、冪等性キーと結果不明時の問い合わせ方法を提案できる。

優秀（Strong）

Problem Details の拡張、部分完了状態、監視カテゴリ、および安全な自動リトライ条件を設計できる。

卓越（Excellent）

ビジネスのアトミック性、依存関係グラフ、補償処理、およびバージョニングされたコントラクトを用いて各選択を論理的に説明し、WebDAV 外で 424 を使用する際の互換性リスクについても指摘できる。

回答戦略

まずステータスコードの標準的な起源を明確にし、次にステップの状態と副作用の境界線を定義します。最後に、照会可能でリトライに対して安全なエラーコントラクトを用いて決定を具体化します。

出典

ステータスコード標準

RFC 4918: WebDAV (IETF)

HTTP セマンティクス

RFC 9110: HTTP Semantics (IETF)

エラー形式

RFC 9457: Problem Details for HTTP APIs (IETF)