Erros

A API x402 utiliza códigos de status HTTP reais. Cada erro possui o mesmo corpo JSON, e retry_action indica ao seu agente o que fazer a seguir.

Corpo do erro

Nome	Tipo	Descrição
erro	String	Código de erro, consulte a tabela abaixo
mensagem	String	Mensagem curta e de fácil compreensão
repetível	Booleano	Se a repetição pode ajudar
retry_action	String	O que fazer: `resign`, `retry_same_payment`, `poll`, `wait_and_retry`, `abandon`, `human_required`
retry_after_seconds	Inteiro	Quando tentar novamente; é igual a `Retry-After` cabeçalho
payment_state	String	`unused`, `in_flight` ou `settled` — se os fundos foram retirados (Repetidas tentativas e idempotência)
authorization_expires_at	String	Até quando sua autorização ainda pode ser executada; não assine uma nova antes de
order_id, operation_id, poll_url	String	A ordem e a operação à qual o pagamento se refere, quando houver
bound_wallet	String	`quote_bound_to_other_wallet`: a carteira que guarda a citação
facilitator_reason	String	Motivo da falha na verificação de pagamento, a partir de uma lista fixa, ou `unknown`
detalhe	String	Detalhes, por exemplo, o caminho do campo inválido: `/items/0/qty: …`

Respostas com uma nova citação (quote_expired, payment_expired, quote_bound_to_other_wallet) também contêm os campos de citação e o PAYMENT-REQUIRED cabeçalho.

{
    "error": "payment_not_settleable",
    "message": "The presented authorization can still be settled",
    "retryable": true,
    "retry_action": "wait_and_retry",
    "retry_after_seconds": 512,
    "payment_state": "unused",
    "authorization_expires_at": "2026-11-02T10:16:00Z"
}

Ações de nova tentativa

retry_action	O que fazer
`resign`	Assine os novos requisitos desta resposta (`PAYMENT-REQUIRED`), ou corrija a solicitação
`retry_same_payment`	Envie a mesma solicitação com o mesmo `PAYMENT-SIGNATURE`. Não crie uma nova
`poll`	Em `202` respostas: enquete `poll_url`
`wait_and_retry`	Recomece (nova citação, nova assinatura) não antes de `retry_after_seconds`
`abandon`	Repetir o mesmo pedido não vai ajudar
`human_required`	Entre em contato com o suporte. Não assine uma nova autorização

Códigos de erro

erro	HTTP	retry_action	Quando
`payment_required`	402	`resign`	Um endpoint pago foi chamado sem `PAYMENT-SIGNATURE`: a citação está na resposta
`payment_invalid`	402	`abandon`	O cabeçalho de pagamento está com formato incorreto ou não está na versão 2 do x402 (`X-PAYMENT` (incluída na versão 1); rede, ativo, destinatário, valor ou período de validade incorretos; falha na verificação da assinatura; uma renovação ou tráfego pago por outra carteira
`insufficient_funds`	402	`wait_and_retry`	A carteira não tem USDC suficiente. Recarregue a carteira e repita a mesma solicitação enquanto a autorização estiver válida
`quote_expired`	402	`resign`	O orçamento está vencido ou já foi pago, e sua autorização também expirou. Um novo orçamento está na resposta
`payment_expired`	402	`resign`	A autorização expirou sem ter sido utilizada ou foi cancelada. Nada foi retirado. Há uma nova cotação na resposta
`invalid_request`	400	`abandon`	Campo inválido, campo desconhecido, JSON inválido, corpo maior que 64 KiB; país, período, quantidade, nível, pacote ou opções indisponíveis; um segundo pacote residencial; regras do endpoint específico
`terms_not_accepted`	400	`resign`	`accept_terms` As versões não estão atualizadas. O corpo do texto contém `offer_version` e `privacy_version`
`purpose_not_allowed`	403	`abandon`	`intended_use` não consta na lista do catálogo
`wallet_rejected`	403	`abandon`	A carteira está bloqueada ou consta de uma lista de sanções
`unauthorized`	401	`abandon`	Não `Authorization: Bearer x402_…` cabeçalho; a assinatura da carteira não corresponde ao desafio
`order_not_found`	404	`abandon`	A ordem não existe ou o token não é válido para ela
`not_found`	404	`abandon`	A recarga ou o desafio não existe, ou o token não é válido para isso
`payment_replayed`	409	`abandon`	A mesma autorização (pagador e nonce) veio com conteúdo diferente
`payment_not_settleable`	409	`wait_and_retry`	A autorização já não é válida, mas sua autorização ainda pode ser executada. Aguarde até `authorization_expires_at` antes de assinar um novo contrato
`payment_under_review`	409	`human_required`	O pagamento está sendo analisado por nossa equipe
`quote_bound_to_other_wallet`	409	`resign`	Outra carteira já utilizou essa citação. Uma nova citação está na resposta
`quote_payment_in_progress`	409	`wait_and_retry`	Outro pagamento referente a este orçamento está sendo processado
`quote_config_mismatch`	409	`abandon`	O conteúdo da solicitação paga não corresponde ao orçamento, ou uma repetição de uma autorização paga traz outra solicitação
`idempotency_key_conflict`	409	`abandon`	Sua carteira já usou isso `idempotency_key` por outro pagamento nas últimas 24 horas
`rate_limited`	429	`wait_and_retry`	Um limite foi excedido (Limites)
`settlement_retry`	503	`retry_same_payment`	O pagamento ainda está sendo processado. Repita a mesma solicitação em `retry_after_seconds`
`channel_paused`	503	`wait_and_retry`	O serviço não está aceitando novos pagamentos temporariamente
`dependency_unavailable`	503	`wait_and_retry`	Uma falha temporária: o preço, o catálogo, a verificação de pagamento ou outro serviço está indisponível
`internal_error`	500	`wait_and_retry`	Erro inesperado

Um método HTTP incorreto retorna 405 com o código invalid_request.

Cada resposta do serviço contém o X-Request-Id cabeçalho. Envie-o ao suporte ao relatar um problema.

Corpo do erro

Ações de nova tentativa

Códigos de erro

On this page