HTTP 402 Payment Required: 의미와 x402의 활용 방식

402 Payment Required의 의미

402 응답은 요청 자체에는 문제가 없지만 결제가 이루어질 때까지 처리되지 않는다는 것을 클라이언트에 알립니다. 다음 행동을 해야 하는 쪽이 서버가 아닌 클라이언트이므로 4xx 계열에 속합니다.

402는 401 Unauthorized, 403 Forbidden과 다릅니다. 401은 인증 정보를 요구하고, 403은 요청을 아예 거부하며, 402는 결제를 요구합니다.

402가 오랫동안 쓰이지 않은 이유

이 코드는 HTTP/1.1이 작성될 당시, 언젠가 일종의 디지털 화폐가 등장할 것이라는 기대 속에 예약되었습니다. 하지만 명세는 402 본문에 무엇을 담아야 하는지, 클라이언트가 어떻게 결제해야 하는지 정하지 않았고, 그래서 브라우저는 이를 처리하지 않았습니다.

공통 형식이 없었기 때문에 402를 반환하는 API들은 이를 단순한 오류로 사용했습니다. 계정 크레딧 소진, 카드 결제 거절, 요금제 한도 도달 같은 경우입니다.

오늘날 API가 402를 반환하는 경우

402는 크게 두 가지 상황에서 볼 수 있습니다.

• 계정 결제 오류: 키는 유효하지만 잔액, 할당량 또는 구독이 요청을 감당하지 못하는 경우입니다. 충전하거나 업그레이드하면 해결됩니다.
• 요청당 결제 견적: 서버가 결제 조건을 반환하고, 클라이언트는 결제한 뒤 같은 요청을 다시 보낼 수 있습니다. x402가 바로 이 방식입니다.

x402가 402를 결제 흐름으로 바꾸는 방식

x402는 금액, 자산, 네트워크, 수취인 등 기계가 읽을 수 있는 조건을 PAYMENT-REQUIRED 헤더에 담습니다. 클라이언트는 그 조건에 대한 스테이블코인 승인에 서명해 PAYMENT-SIGNATURE 헤더로 돌려보내고, PAYMENT-RESPONSE 영수증과 함께 응답을 받습니다.

전체 과정이 일반 HTTP로 이루어지므로, 지갑을 가진 AI 에이전트는 가입하거나 API key를 저장하지 않고도 API 호출 비용을 결제할 수 있습니다.

클라이언트에서 402 처리하기

먼저 PAYMENT-REQUIRED 헤더가 있는지 확인하세요. 헤더가 있다면 응답은 x402 견적이며 x402 클라이언트로 결제할 수 있습니다. 없다면 오류 본문을 읽으세요. 대개 계정에 크레딧을 추가하거나 요금제를 바꿔야 한다는 뜻입니다.