Status de resposta
O corpo do erro
Os erros400, 401 e 404 vêm com um JSON de campo único error, trazendo a mensagem em português. O corpo real do 401, confirmado pela engenharia, é:
429: a resposta é a página HTML padrão do servidor, sem JSON e sem o header Retry-After. Não tente fazer parse do corpo de um 429; decida pelo status. Dois fatos importantes sobre o contrato de erros:
Não existe código de erro interno. O status HTTP é o único identificador estruturado; a mensagem existe para humanos. Portanto, decida pelo status na sua lógica (retry, alerta, correção) e use a mensagem para logs e diagnóstico, nunca como condição de código, porque o texto pode mudar.
Erros de validação vêm em mensagem única, não em lista por campo. Se o payload tiver mais de um problema, a API aponta um por vez: corrija, reenvie e repita até o 200.
Receita de tratamento
Na prática, a sua integração precisa de três comportamentos: 400 e 404 não se repetem sozinhos (reenviar o mesmo payload dá o mesmo erro; corrija antes), 401 é configuração (pare e revise o token, sem retry automático), e 429 e 5xx pedem retry com espera crescente (1 s, 2 s, 4 s, 8 s…), respeitando o ritmo de 2 requisições por segundo nas varreduras de sincronização.Retry com backoff exponencial
O429 é o erro mais provável da sua integração, porque o limite de 2 requisições por segundo é fácil de estourar em varreduras. Como não há header Retry-After, comece com 1 segundo e dobre a espera a cada falha seguida.
400, 401 e 404 ficam de fora do retry: eles não se resolvem com espera.
Próximos passos
Limites de requisição
O rate limit oficial e como ritmar as suas chamadas.
Autenticação
O checklist completo para nunca ver um 401.