HTTP 402 Payment Required: o que significa e como o x402 o usa
402 é o código de status HTTP para uma requisição que precisa de pagamento antes que o servidor a atenda. Por boa parte de sua história, não teve um formato padrão. O x402 dá um a ele.
Key takeaways
-
402 Payment Required é um erro de cliente: a requisição é válida, mas o servidor quer o pagamento primeiro.
-
O HTTP/1.1 reservou o 402 para uso futuro e nunca definiu como o pagamento deveria funcionar, então cada API o usou de um jeito diferente.
-
O x402 define as peças que faltavam: um cabeçalho PAYMENT-REQUIRED com termos legíveis por máquina e um pagamento assinado na nova tentativa.
O que significa 402 Payment Required
Uma resposta 402 informa ao cliente que a requisição em si está correta, mas não será atendida até que o pagamento seja feito. Ela pertence à família 4xx porque quem precisa agir em seguida é o cliente, não o servidor.
402 é diferente de 401 Unauthorized e 403 Forbidden. 401 pede credenciais, 403 recusa a requisição de imediato, e 402 pede pagamento.
Por que o 402 ficou sem uso por tanto tempo
O código foi reservado quando o HTTP/1.1 foi escrito, com a expectativa de que alguma forma de dinheiro digital surgiria depois. A especificação nunca disse o que um corpo 402 deveria conter nem como um cliente deveria pagar, então os navegadores nunca agiram sobre ele.
Sem um formato compartilhado, as APIs que de fato retornavam 402 o usavam como um erro simples: uma conta sem créditos, um cartão recusado, ou um limite de plano atingido.
Quando as APIs retornam 402 hoje
Você vai encontrar o 402 em duas situações amplas.
- Erros de cobrança da conta: a key é válida, mas o saldo, a cota ou a assinatura não cobrem a requisição. A solução é recarregar ou fazer upgrade.
- Cotações de pagamento por requisição: o servidor retorna os termos de pagamento, e o cliente pode pagar e tentar novamente a mesma requisição. É assim que o x402 funciona.
Como o x402 transforma o 402 em um fluxo de pagamento
O x402 coloca termos legíveis por máquina em um cabeçalho PAYMENT-REQUIRED: valor, ativo, rede e destinatário. Um cliente assina uma autorização de stablecoin para esses termos, envia de volta em um cabeçalho PAYMENT-SIGNATURE, e recebe a resposta com um recibo PAYMENT-RESPONSE.
Como toda a troca é HTTP puro, um agente de IA com uma wallet pode pagar uma chamada de API sem se cadastrar ou armazenar uma API key.
Lidando com um 402 no seu cliente
Verifique primeiro se há um cabeçalho PAYMENT-REQUIRED. Se houver, a resposta é uma cotação x402 que um cliente x402 pode pagar. Se não houver, leia o corpo do erro: geralmente significa que a conta precisa de mais créditos ou de um plano diferente.
FAQ sobre HTTP 402
402 Payment Required é um erro?
É um erro de cliente na faixa 4xx, mas não significa que a requisição estava malformada. Significa que é preciso pagamento antes de o servidor continuar.
Qual é a diferença entre 402 e 401?
401 significa que o servidor precisa de credenciais válidas. 402 significa que o servidor precisa de pagamento. Uma API pode retornar 401 para uma key inválida e 402 para uma key válida sem saldo.
Os navegadores tratam o 402 automaticamente?
Não. Os navegadores mostram um 402 como qualquer outra página de erro. O pagamento automático precisa de um cliente que entenda um protocolo como o x402.
Quais APIs usam 402 com x402?
Qualquer servidor que implemente o protocolo x402. A RunAPI retorna cotações x402 em seus endpoints de modelos de IA cobrados por chamada, permitindo que um agente pague em USDC pela geração de imagem, vídeo, música e áudio.
Páginas relacionadas
Pague por requisição em USDC na Base, sem API key.
Todos os modelos e endpoints disponíveis na RunAPI.
Formatos de requisição, consulta de tarefas e códigos de erro.
Créditos, preços por chamada e detalhes de cobrança.
Experimente um 402 que você realmente consegue pagar
Envie uma requisição a um endpoint da RunAPI cobrado por chamada sem uma key e examine a cotação x402 retornada.