Skip to main content
API v2 A v2 sinaliza falhas pelo status HTTP e devolve o motivo em um corpo JSON, no mesmo contrato da plataforma SULTS confirmado pela engenharia.

Status de resposta

O corpo do erro

Os erros 400, 401 e 404 vêm com a mensagem em um JSON simples. O corpo real do 401, confirmado pela engenharia:
E um 400 real de validação:
O 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

O 429 é 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.
Repare que 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.