Erros e status

Todo erro da API vem num envelope JSON com código estável e mensagem em português.

Envelope de erro

4xx / 5xx

{
  "error": {
    "code": "invalid_amount",
    "message": "amount_cents deve ser um inteiro positivo (em centavos)"
  }
}

Programe contra o campo code (estável); a message é para humanos e pode mudar.

Parâmetro	Tipo	Descrição
`unauthorized`	401	Chave ausente, inválida ou revogada — ou tipo errado de credencial para a rota.
`invalid_body`	400	JSON malformado ou com campos desconhecidos.
`invalid_amount`	400	amount_cents ausente, zero ou negativo.
`invalid_limit`	400	limit não numérico ou negativo na listagem.
`not_found`	404	Recurso inexistente — ou de outra conta (não vazamos existência).
`not_simulatable`	403	simulate-payment fora do sandbox.
`internal_error`	500	Falha inesperada do nosso lado. Tente de novo em instantes.

Parâmetro	Tipo	Descrição
`pending`	status	Criada, aguardando pagamento.
`paid`	status	Paga. O paid_at marca o momento da confirmação.
`expired`	status	Expirou sem pagamento.
`failed`	status	Falhou no provedor.