Erros

Códigos

code	HTTP	O que fazer
invalid_signature	401	Ver Autenticação
forbidden	403	A conta não pode operar agora. Falar com o seu provedor
kyc_limit_exceeded	403	O valor passou do teto do nível de verificação da conta
validation_failed	422	details traz campo → lista de mensagens
service_temporarily_unavailable	503	Recuo exponencial. A operação não aconteceu
not_found	404	O recurso não existe — ou não é seu
rate_limited	429	Esperar Retry-After segundos

503 significa que nada aconteceu

service_temporarily_unavailable é a resposta quando a operação não pode ser processada agora. A cobrança não foi criada. Repetir é seguro, com recuo exponencial.

Uma chave de teste numa conta sem ambiente de teste configurado recebe isto — e é a resposta honesta. A alternativa seria roteá-la para produção e você descobrir movimentando dinheiro de verdade.

429 traz o tempo de espera

O cabeçalho Retry-After diz quantos segundos esperar, e error.details.retryAfter repete o número no corpo.

Respeite-o. A reação natural — tentar de novo na hora — piora exatamente a saturação que o limite existe para conter.

Se você está batendo no limite consultando estado em laço, o problema não é o limite: é o laço. Use webhooks.

404 também é "não é seu"

Um recurso de outra conta responde 404, não 403.

Dizer "existe, mas você não pode" entrega informação a quem sonda. Se você recebeu 404 num id que você acabou de criar, confira se está usando a credencial da conta certa.

O que você nunca vai receber

Nenhum erro devolve stack trace, nome de serviço interno ou detalhe de infraestrutura. Quando algo falha do nosso lado, você recebe error.code e o meta.requestId — que é o que o suporte precisa.