402 Payment Required: Not an Error, a Gate

문제

200을 기대했는데 402 Payment Required가 돌아왔습니다. 본능적으로 에러처럼 디버깅하게 됩니다 — 페이로드를 확인하고, 문서를 다시 읽고, 헤더를 바꿔 재시도하고. 멈추세요. 402는 거의 버그가 아니고, 버그처럼 다루면 오후를 통째로 날립니다.

RFC 9110 §15.5.3은 이 코드를 한 문장으로, 그것도 이상하게 정의합니다: 402 (Payment Required) 상태 코드는 향후 사용을 위해 예약되어 있다. 그게 명세 전부입니다. 90년대 중반으로 거슬러 올라가는 원래 아이디어는 서버가 “먼저 돈 내라”고 말하는 표준 방식 — 끝내 만들어지지 않은 디지털 캐시용 후크였습니다. 그래서 숫자만 예약되고 그 주변 프로토콜은 비워졌습니다: 가격을 명시할 표준 헤더도, 결제 요구의 정의된 형식도 없습니다.

그 공백이 402를 헷갈리게 만듭니다. 명세가 뜻을 못 박지 않았으니, 기계가 읽을 수 있는 “당신은 돈을 내야 한다”가 필요했던 서비스마다 각자의 정의를 채워 넣었습니다. 결론은 402가 하나의 조건이 아니라는 것입니다. 그것은 의도된 관문의 한 집합이고, 해법은 요청을 고치는 게 아니라 어떤 관문에 걸렸는지 알아내는 것입니다.

증상

• 상태 줄이 402 Payment Required로 나오고, 대개 구체적 이유를 담은 JSON·HTML 본문이 따라옵니다 — 미납 청구서, 초과된 할당량, 필요한 구독.
• 되던 요청이 안 되기 시작하거나, 같은 호스트의 무료 엔드포인트는 200인데 “프리미엄”·“유료 티어”로 문서화된 엔드포인트에서만 나타납니다.
• 같은 자격 증명으로 재시도해도 아무것도 안 바뀝니다 — 요청에 잘못된 게 없기 때문입니다.
• 운영자라면 모든 페이지가 한꺼번에 402를 반환하기 시작합니다. 이건 단일 엔드포인트가 아니라 플랫폼 수준의 동결을 가리킵니다.

주요 원인 3가지

1. 과금형 API가 할당량에서 끊음 - 개발자가 가장 흔히 만나는 경우입니다. 무료·상한 요금제인데 월 요청 한도를 넘겼거나 선불 크레딧을 다 썼고, API가 데이터 대신 402를 답합니다. 응답 본문이 한도를 명시합니다. 해법은 요금제 상향, 크레딧 구매, 또는 할당량 창이 리셋될 때까지 대기입니다. 코드는 멀쩡합니다 — 예산이 떨어진 겁니다.
2. 호스팅형 플랫폼이 청구 문제로 계정을 동결 - 운영자의 경우입니다. 잔액이 연체된 커머스·호스팅 플랫폼이 자산 전체를 동결하고 방문자에게 402를 서빙합니다. Shopify API가 문서화된 예입니다: 동결된 스토어는 관리자가 미납 잔액을 정산할 때까지 402를 반환합니다. 스토어 코드는 아무것도 안 바뀌었고, 결제가 밀린 겁니다.
3. 네이티브 결제 프로토콜이 일부러 돈을 요구 - 가장 새로운 경우이자 402를 원래 상상대로 쓰는 경우입니다. L402(Lightning 인보이스 + 능력 토큰)나 x402 같은 방식은 결제 요구를 응답에 담아 402를 보내고, 클라이언트 — 점점 더 자동화된 에이전트 — 가 값을 치르고 증빙과 함께 재시도하기를 기대합니다. 여기서 402는 실패가 아니라 유료 관문 핸드셰이크의 1단계이고, 본문이 어떻게 내는지 정확히 알려줍니다.

DechoNet으로 진단하기

• HTTP 점검은 URL의 원시 상태 줄, 응답 헤더, 본문 앞부분을 보여줍니다. 이유가 사는 곳이 바로 거기입니다: 402는 거의 항상 설명을 실어 보냅니다 — 인보이스 ID, 할당량 메시지, 또는 결제 요구 — 그걸 읽으면 셋 중 어느 원인인지 알 수 있습니다. 밋밋한 페이지가 호스트 전체에서 402면 플랫폼 동결이고, 특정 유료 엔드포인트만 그러면 할당량이나 유료 관문입니다.
• 응답 헤더의 Content-Type과 플랫폼이 청구 상태를 서술하는 커스텀 X-* 필드를 확인해 이 차단이 우연이 아니라 의도된 것인지 검증하세요. 깔끔하고 구조화된 본문의 402는 설계된 관문이고, 일반 에러 페이지의 402는 청구 콘솔까지 추적할 플랫폼 기본값입니다.

해결 체크리스트

• 응답 본문부터 읽으세요. curl -i https://api.example.com/endpoint로 402가 실제로 뭐라고 하는지 보세요 — 예상보다 훨씬 자주 이유를 명시합니다.
• 누가 보냈는지 특정하세요: 당신의 호스팅·커머스 플랫폼(운영자)인가, 당신이 호출하는 서드파티 API(개발자)인가. 이 구분 하나가 다음 행동을 정합니다.
• 과금형 API라면 요금제 사용량과 청구 대시보드를 확인하세요. 상향, 크레딧 충전, 또는 리셋 창까지 대기. 요청을 바꾸지 마세요 — 그건 문제가 아닙니다.
• 당신의 플랫폼이라면 유료 서비스마다 청구 상태를 확인하세요: 호스팅, 커머스 플랫폼, 과금형 의존성. 연체 잔액을 정산하면 402가 걷힙니다.
• 본문이 결제 요구(L402, x402, Lightning 인보이스)를 담고 있다면 유료 관문 핸드셰이크에 걸린 것입니다. 흐름을 따르세요: 지불하고, 증빙·토큰을 확보하고, 그걸 붙여 재시도.
• 이 모든 걸 배제한 다음에야 오설정을 의심하세요 — 게이트웨이가 다른 조건을 실수로 402에 매핑한 경우. 드물고, 첫 번째가 아니라 마지막에 확인할 것입니다.

언제 에스컬레이션할까

• 지불·충전·정산을 마쳤는데도 제공자가 안내한 반영 시간을 넘겨 402가 지속되면, 그쪽 청구 시스템 문제입니다. 인보이스·계정 ID를 들고 제공자에 문의하세요 — 멈춘 청구 상태는 클라이언트에서 못 고칩니다.
• 결제 네이티브 API(x402, L402)를 연동 중인데 증빙-재시도 단계가 계속 402를 반환하면, 문제는 결제 자체가 아니라 결제 토큰을 제시하는 방식에 있습니다. 전체 요청·응답을 캡처해 토큰 형식을 문서와 대조하세요.
• 유료가 될 리 없는 엔드포인트에 402가 뜬다면 — 할당량도, 구독도, 청구 관계도 없는데 — 경로 어딘가가 코드를 오용하는 것입니다. 어느 홉이 주입하는지 추적하세요. 프록시나 게이트웨이가 무관한 실패를 402에 매핑하는 건 근원에서 고칠 만한 설정 버그입니다.