Lide com limites de taxa e erros do servidor

Lide com uma resposta 429

Uma solicitação limitada por taxa devolve 429 Too Many Requests, com detail.status igual a rate_limit_exceeded. Leia os cabeçalhos antes de repetir:

• Retry-After informa a espera mínima em segundos para a solicitação rejeitada.
• X-RateLimit-Limit informa o limite do grupo.
• X-RateLimit-Remaining informa quantas solicitações restam.
• X-RateLimit-Reset informa quando o grupo será redefinido.

Espere o Retry-After e tente novamente com espera exponencial e variação aleatória. Reduza solicitações paralelas e enfileire o trabalho em vez de enviar uma rajada quando a janela reiniciar.

Lide com erros do servidor

Para uma resposta 500, o corpo público contém um erro genérico e um request_id, sem detalhes da exceção interna. 503 pode indicar indisponibilidade temporária de um serviço necessário.

Repita solicitações somente de leitura com esperas e número limitado de tentativas. Antes de repetir uma criação, atualização, pagamento ou outra alteração de estado, verifique se a primeira tentativa foi concluída. Timeout ou 5xx não provam falha; repetir de imediato pode duplicar a operação.

Guarde dados de diagnóstico

Registre data e hora, método, caminho, status, corpo da resposta e X-Request-Id. Nunca registre o valor de x-api-key. Interrompa as tentativas automáticas depois de um pequeno número e encaminhe a falha para análise.