202は受付と完了を区別する

受付後も処理中のタスクと、別の状態確認先を示す抽象的なサーバー・クライアントの流れ

時間のかかるエクスポートや大量変換を受け付けても、サーバーが完了まで接続を維持する必要はない。202 Acceptedは処理対象として受け付けたものの、処理はまだ完了していないことを示す。RFC 9110は、実際の処理時に拒否される可能性もあるため、この応答は意図的に確約を避けていると説明する。画面には「完了」ではなく「受付済み」または「処理中」と表示する。IETF RFC 9110 §15.3.3

状態を確認する方法を示す

202の応答表現には現在の状態を記し、完了見込みを確認できるステータスモニターを示すことが望ましい。実装例として、ジョブIDと/jobs/{id}のようなURL、queued、running、succeeded、failedなどの状態を返せる。ただしURL形式や状態名はHTTP標準で決まっていない。

状態取得は送信と分けた読み取り要求にする。最終更新時刻、結果、失敗理由などを返し、推測しやすいジョブIDから他人の結果が見えないよう認可を確認する。

再確認間隔をAPI契約で定める

頻繁なポーリングは処理が遅い間も通信を増やす。初回確認まで待ち、処理中なら間隔を広げるか、サービスが明示する案内に従う方法がある。RFC 9110のRetry-Afterは503時の利用不能見込み時間と、3xxリダイレクト先へ進む前に求める最短待ち時間を定義する。202のポーリング間隔を決めるものではない。API独自のヒントは意味と単位を文書化する。IETF RFC 9110 §10.2.3

接続が切れても結果は分からない

202を返した後、接続を閉じてもサーバー処理が続くことがある。受付済みでも最終成功は保証されない。状態取得がタイムアウトしたら結果を推測せず、同じジョブIDで再確認する。最初の送信応答を受け取れなかった場合、受付の有無は分からないため、再送でジョブが重複しないよう別途対策が必要だ。RFC 9110は非同期処理の結果を元の接続に後から返すHTTP機能はないと明記する。

状態リソースは「処理中」と繰り返すだけでなく、利用者が次に何をできるかを伝えると役立つ。タスク識別子、現在の段階、最終更新時刻、完了後の結果リンクなどを設計できる。これらはRFC 9110が定める形式ではなく、サービス側の契約である。完了予想時刻を示すなら推定値であり、状況に応じて変わることも説明する。

状態確認先には独自の認可と保存期間の問題もある。URLを知っているだけで他人の結果を読めないよう、状態と成果物の双方でアクセスを確認する。状態をいつ削除するか、期限切れURLは何を返すか、再送した提出を以前のタスクとどう関連づけるかも決める。提出応答の消失と状態確認の失敗は別の不確実性である。前者では受付済みか分からない場合があり、後者では処理結果がまだ分からないだけかもしれない。冪等キーや回復手順は扱いを助けるが、202自体はその仕組みを定義しない。

クライアントが状態を誤解しないよう、待機・実行中と、成功・失敗・取消などの終端状態を区別する設計も必要です。HTTP標準は状態名を指定しないため、API契約で各値の意味を定めます。

専門家向け資料と標準の範囲

Roy T. Fielding、Mark Nottingham、Julian Reschkeが編集したRFC 9110はHTTP意味論の規範仕様である。202が未完了の処理受付を表すこと、現在の状態を説明してモニターを示すことが望ましい点を定める。キュー、確認間隔、保持期間、キャンセル、重複送信の扱いは定めていない。処理時間、コスト、セキュリティ要件に合わせてAPI契約で決める。

HTTP標準だけで再試行頻度や待機時間が決まるわけではありません。クライアントとサーバーが同じ契約を参照できるよう、公開APIの説明も確認します。

出典

IETF, RFC 9110: HTTP Semantics, §§15.3.3 and 10.2.3 MDN Web Docs: 202 Accepted