Formato do erro
Falhas retornam um objeto error com code e message. Sempre programe contra o code — a message pode mudar sem aviso.
Corpo de erro
{
"error": {
"code": "invalid_amount",
"message": "amount deve ser um inteiro em centavos entre 1 e 5000000"
}
}Códigos de erro
| Código | HTTP | Quando acontece |
|---|---|---|
unauthorized | 401 | Chave de API ausente, malformada, revogada ou inexistente. |
invalid_request | 400 | Corpo inválido: JSON malformado ou campo obrigatório faltando. |
invalid_amount | 400 | amount fora da faixa permitida ou não inteiro (em centavos). |
not_found | 404 | Recurso inexistente ou que não pertence à sua conta. |
rate_limited | 429 | Reservado. Volume alto demais de requisições em curto período. |
rate_limited (429) está reservado para uso futuro: hoje a API não aplica limite de taxa, mas o código já faz parte do contrato para que sua integração o trate desde já.Como tratar
Verifique o status HTTP e o error.code. Códigos 4xx indicam algo a corrigir na requisição (não adianta repetir sem mudança); 5xx, quando ocorrerem, podem ser reprocessados com backoff.