HTTP 402 Payment Required：その意味とx402での使われ方
402は、サーバーがリクエストに応じる前に支払いを求めることを示すHTTPステータスコードです。長い間、標準的な形式はありませんでした。x402がその形式を定めます。
Key takeaways
-
402 Payment Requiredはクライアントエラーです。リクエスト自体は有効ですが、サーバーは先に支払いを求めています。
-
HTTP/1.1は402を将来の利用のために予約しましたが、支払いの方法は定義しなかったため、APIごとに使い方がばらばらでした。
-
x402は欠けていた部分を定義します。機械可読な条件を記したPAYMENT-REQUIREDヘッダーと、再送時の署名済み支払いです。
402 Payment Requiredの意味
402レスポンスは、リクエスト自体に問題はないものの、支払いが行われるまで処理されないことをクライアントに伝えます。次に行動すべきなのはサーバーではなくクライアントなので、4xx系に属します。
402は401 Unauthorizedや403 Forbiddenとは異なります。401は認証情報を求め、403はリクエストをそのまま拒否し、402は支払いを求めます。
402が長く使われなかった理由
このコードはHTTP/1.1の策定時に、いずれ何らかのデジタル通貨が登場することを見込んで予約されました。しかし仕様は402のボディに何を含めるべきか、クライアントがどう支払うべきかを定めなかったため、ブラウザがこれに対応することはありませんでした。
共通の形式がなかったため、402を返すAPIはそれを単なるエラーとして使っていました。アカウントのクレジット切れ、カードの決済拒否、プランの上限到達などです。
現在APIが402を返す場面
402が返されるのは、大きく分けて次の2つの状況です。
- アカウントの請求エラー：キーは有効でも、残高、クォータ、サブスクリプションがリクエストをカバーしていない場合です。チャージまたはアップグレードで解決します。
- リクエストごとの支払い見積もり：サーバーが支払い条件を返し、クライアントは支払ったうえで同じリクエストを再送できます。x402はこの仕組みです。
x402が402を決済フローに変える仕組み
x402は、金額、資産、ネットワーク、受取人といった機械可読な条件をPAYMENT-REQUIREDヘッダーに記載します。クライアントはその条件に対するステーブルコインの承認に署名してPAYMENT-SIGNATUREヘッダーで送り返し、PAYMENT-RESPONSEの領収書付きでレスポンスを受け取ります。
やり取り全体が通常のHTTPで完結するため、ウォレットを持つAIエージェントは、登録やAPI keyの保管なしにAPI呼び出しの料金を支払えます。
クライアントでの402の扱い方
まずPAYMENT-REQUIREDヘッダーの有無を確認します。ヘッダーがあれば、そのレスポンスはx402の見積もりで、x402クライアントで支払えます。なければエラーボディを読んでください。多くの場合、アカウントのクレジット追加やプラン変更が必要という意味です。
HTTP 402に関するよくある質問
402 Payment Requiredはエラーですか？
4xx系のクライアントエラーですが、リクエストの形式が不正という意味ではありません。サーバーが処理を続ける前に支払いが必要という意味です。
402と401の違いは何ですか？
401はサーバーが有効な認証情報を必要としていることを、402は支払いを必要としていることを意味します。APIは無効なキーには401を、残高のない有効なキーには402を返すことがあります。
ブラウザは402を自動で処理しますか？
いいえ。ブラウザは402を他のエラーページと同じように表示します。自動で支払うには、x402のようなプロトコルを理解するクライアントが必要です。
x402で402を使っているのはどのAPIですか？
x402プロトコルを実装しているすべてのサーバーです。RunAPIは従量課金のAIモデルエンドポイントでx402見積もりを返すため、エージェントは画像、動画、音楽、音声の生成をUSDCで支払えます。