Status de resposta
O corpo do erro
Os erros400, 401 e 404 vêm com a mensagem em um JSON simples. O corpo real do 401, confirmado pela engenharia:
429 é a exceção: a resposta é a página HTML padrão do servidor, sem JSON e sem o header Retry-After; trate pelo status, sem parse do corpo. Não existe código de erro interno: decida pelo status na sua lógica e use a mensagem para logs. Erros de validação vêm em mensagem única, um campo por vez: corrija, reenvie e repita até o 200.
Receita de tratamento
400 e 404 não se resolvem sozinhos (corrija antes de reenviar), 401 é configuração (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 descrito em limites de requisiçã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.