Skip to content
ENPT

Código de status HTTP · Erros do cliente (4xx)

Erro 402 Payment Required

O 402 Payment Required está oficialmente "reservado para uso futuro", então nenhum padrão define o que o cliente deve fazer com ele. Na prática, ele aparece quando uma API ou plataforma recusa o serviço por causa de cobrança: cartão recusado, fatura em aberto ou limite do plano.

Dados sobre este código de status
Classe4xx, Erros do cliente
Definido emRFC 9110 §15.5.3
Pode ir para o cache por padrãoSó com Cache-Control ou Expires explícitos
Pode repetir o pedidoDepois de resolver o pagamento ou a cobrança
Cabeçalhos relevantesNenhum específico deste código
SituaçãoObsoleto: Reservado para uso futuro pela RFC 9110; não existe comportamento padrão.

O que significa o 402

O código está reservado desde os rascunhos do HTTP/1.1, nos anos 1990, quando se esperava que micropagamentos por conteúdo na web chegassem logo. A RFC 9110, seção 15.5.3, ainda diz apenas que ele está reservado, e os navegadores não fazem nada de especial ao recebê-lo.

Mesmo assim, fornecedores passaram a usá-lo. A API da Stripe devolve 402 "Request Failed" quando os parâmetros estavam certos mas a operação falhou, como um cartão recusado. A API da Shopify devolve 402 quando uma loja está congelada por saldo em aberto. O protocolo x402, publicado pela Coinbase em 2025, usa respostas 402 com instruções de pagamento para que programas paguem por requisição.

Causas comuns

Se você está visitando o site

  • A assinatura venceu ou o cartão cadastrado foi recusado, e o serviço pausou a conta.
  • Você atingiu a cota de um plano gratuito ou pago (chamadas de API, exportações, usuários).

Se você administra o servidor

  • Uma chamada à API de pagamento falhou por motivo de negócio, como a Stripe informando cartão recusado com 402.
  • A sua aplicação traduz "limite do plano atingido" ou "conta suspensa por falta de pagamento" em 402.

Como resolver

Se você está visitando o site

  • Abra a página de cobrança do serviço e atualize a forma de pagamento ou quite a fatura em aberto.
  • Mude de plano ou espere a cota renovar se a mensagem falar em limite.

Se você administra o servidor

  • Ao consumir uma API de pagamento, leia o corpo do erro (a Stripe inclui um decline_code) em vez de decidir só pelo status.
  • Se você mesmo enviar 402, coloque no corpo um motivo legível por máquina e o link da página de cobrança; clientes não têm forma padrão de interpretar o código.
  • Considere um 403 com mensagem clara, se seus clientes ou proxies lidam mal com esse uso não padronizado do 402.

Como enviar um 402

Express (Node.js)
app.post('/exports', (req, res) => {
  res.status(402).json({ error: 'Monthly export limit reached', billing_url: '/settings/billing' });
});
Next.js App Router (route handler)
// app/exports/route.ts
export async function POST() {
  return Response.json(
    { error: 'Monthly export limit reached', billing_url: '/settings/billing' },
    { status: 402 }
  );
}
Go net/http
mux.HandleFunc("POST /exports", func(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusPaymentRequired) // 402
	w.Write([]byte(`{"error":"Monthly export limit reached","billing_url":"/settings/billing"}`))
})
Python FastAPI
from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

@app.post("/exports")
def create_export():
    return JSONResponse(status_code=402, content={"error": "Monthly export limit reached", "billing_url": "/settings/billing"})

Costuma ser confundido com

402 vs 403
O 403 é uma recusa genérica com significado padronizado; o 402 especifica que o motivo é pagamento, mas não tem comportamento padrão no cliente.
402 vs 429
O 429 é um limite de taxa que passa com o tempo; um limite de plano com 402 só passa depois de pagar ou mudar de plano.

Perguntas frequentes

O 402 Payment Required é um código oficial?
Ele está registrado, mas a RFC 9110 o marca como reservado para uso futuro e não define semântica. Qualquer significado vem da API que o envia.
Por que a Stripe devolve erro 402?
A Stripe usa 402 "Request Failed" quando o pedido era válido mas não pôde ser concluído, na maioria das vezes um cartão recusado. O objeto de erro no corpo diz o motivo, com um decline_code nas falhas de cartão.
Minha API SaaS deve usar 402 para assinatura vencida?
Muitas usam, e o sinal fica claro para quem integra. Coloque o motivo e o link de cobrança no corpo, porque clientes HTTP genéricos tratam o 402 como qualquer outro erro 4xx.

Revisado em por Arielton Oberek.