# Erros

Toda recusa traz `message` com o motivo em português. Quando o motivo é útil
para si, dizemo-lo; quando dizê-lo ajudaria quem está a atacar, não dizemos — e
esta página explica quais são os casos.

## Estados

| | Quando | O que fazer |
|---|---|---|
| `400` | O pedido está malformado, ou falta um cabeçalho obrigatório | Corrigir e repetir |
| `401` | A chave falta, está errada ou foi revogada | Verificar a chave |
| `403` | A chave é válida e não tem permissão para esta operação | Ver o guia de autenticação |
| `404` | Não existe **ou não é da sua loja** | Ver abaixo |
| `409` | A mesma chave de idempotência com um corpo diferente | Não reutilizar chaves entre pedidos distintos |
| `422` | O corpo é válido em forma e não em conteúdo — valor acima do que resta num estorno, cobrança num estado que não permite a operação | A `message` diz qual |
| `429` | Limite de chamadas | Esperar o `Retry-After` |
| `502` | O adquirente recusou ou não respondeu | Não é erro seu; repetir mais tarde |

## Por que `404` e não `403` para recurso de outra loja

Responder "existe, mas não é seu" conta a quem pergunta que aquele id existe.
Repetido com paciência, isso desenha o mapa dos clientes de outra pessoa. Um
`404` não conta nada.

## Por que uma recusa de cartão não diz o motivo

O emissor sabe porque recusou; nós sabemos que recusou. Repetir o motivo em voz
alta ajuda sobretudo quem está a testar cartões roubados a perceber quais
passam.

O que a `message` diz é o que é útil ao lojista: que foi recusado, e que pode
tentar outro meio.

## `429`: o que fazer e o que não fazer

**Espere o `Retry-After`.** Repetir de imediato prolonga o bloqueio e desperdiça
a sua quota.

Os limites são calibrados para volume de gateway, e há baldes diferentes: os
webhooks dos adquirentes têm o mais folgado, a autorização de pagamento tem o
mais apertado — é a chamada que custa dinheiro de verdade.

Se está a bater no limite com tráfego legítimo, fale connosco antes de contornar.

## O que fazer quando não há resposta

Se a chamada não devolveu nada — a ligação caiu, o tempo esgotou —, **não assuma
que não aconteceu**. Repita com a **mesma** chave de idempotência: se tinha
acontecido, devolvemos o mesmo resultado; se não, acontece agora.

É a diferença entre repetir e cobrar duas vezes.