Ganhos:
- Pode interpretar limites de velocidade (RPM/ITPM/OTPM) e erros 429
- Implementa espera exponencial e nova tentativa com nova tentativa após
- Classifica e trata corretamente códigos de erro HTTP comuns (400/401/429/500/529)
Em um ambiente de produção, nenhuma API responde perfeitamente o tempo todo. Às vezes você envia solicitações muito rapidamente e atinge o limite; às vezes o servidor fica temporariamente ocupado; Às vezes, sua solicitação está errada desde o início. O que distingue uma integração sólida de uma tentativa amadora é que ela lida com essas situações de forma preditiva e automática. Nesta unidade, você aprenderá sobre limites de taxa (RPM/ITPM/OTPM), erro 429, nova tentativa com espera exponencial e classificação adequada de códigos de erro HTTP comuns. O objetivo: construir um fluxo tão robusto que o usuário nunca notará.
O que são limites de velocidade?
O provedor limita quanto trabalho um switch pode realizar em um determinado período de tempo. Esta proteção; Ele protege a infraestrutura e você contra explosões repentinas de custos. Existem três tipos comuns de limites:
- RPM (Solicitações por Minuto): Número de solicitações por minuto.
- ITPM (Input Tokens Per Minute): Token de entrada que pode ser processado por minuto.
- OTPM (Tokens de Saída por Minuto): Token de saída que pode ser produzido por minuto.
Se você exceder algum desses limites, o provedor rejeitará a solicitação e retornará um código de erro 429. Os limites geralmente variam dependendo do nível da sua conta (nível) e podem ser aumentados com o tempo.
Dica: você pode observar quando está se aproximando do limite nos cabeçalhos de resposta. A maioria dos provedores informa sua cota restante com cabeçalhos como x-ratelimit-remaining-*. Monitorar esses valores e acelerar o trânsito à frente é a forma mais madura de prevenir o problema sem conseguir um 429.
429 e retração exponencial
429 (limite de taxa) é um erro temporário e que pode ser repetido. A resposta correta é aguardar um pouco a solicitação e tentar novamente. Mas uma espera constante não é suficiente; Se todos tentarem novamente ao mesmo tempo, o limite será atingido novamente. A solução é a espera exponencial: aumentar exponencialmente o tempo de espera a cada tentativa fracassada.
# Teste de lógica de backoff exponencial 1 → 429 → espere 1 segundo de teste 2 → 429 → espere 2 segundos de teste 3 → 429 → espere 4 segundos de teste 4 → 429 → espere 8 segundos (+ pequeno "jitter" aleatório)... desista e relate após no máximo N tentativas
Adicionar um pouco de aleatoriedade (jitter) evita que as solicitações colidam ao tentar novamente ao mesmo tempo. Além disso, a resposta 429 geralmente carrega um cabeçalho `retry-after`: "tente novamente nestes segundos". Respeitar este título é mais correto do que esperar cegamente.
Cuidado: Quando você receber um 429, “forçar enviando mais solicitações” piorará a situação; O limite continua a ser preenchido e nenhuma solicitação é processada. A resposta correta é recuar, não acelerar. Boas notícias: a maioria dos SDKs oficiais tenta novamente erros 429 e de servidor automaticamente com uma espera – use este comportamento do SDK antes de instalá-lo manualmente.
Classificação de códigos de erro HTTP
Nem todo erro é igual. Distinção crítica: pode ser repetida ou é um problema de solicitação/identidade?
Código
Significado
Pode ser tentado novamente?
resposta correta
400
Solicitação inválida (erro de formato/parâmetro)
não
Corrija a solicitação; não envie o mesmo novamente
401
Erro de autenticação (chave inválida/ausente)
não
Corrigir chave/título
403
Sem autorização (sem acesso ao modelo/recurso)
não
Verifique permissões/escopo
404
Não encontrado (ID de modelo/endpoint incorreto)
não
ID/endereço correto do modelo
429
Limite de velocidade excedido
Sim
Recuar + tentar novamente depois
500
Erro no servidor
Sim
Tente novamente com retirada
529
Servidor sobrecarregado
Sim
Tente novamente com retirada
Regra de ouro: 429, 500 e 529 são temporários; É tentado novamente com retirada. 400, 401, 403, 404 são problemas de solicitação/identidade; Tentar novamente não resolverá o problema e desperdiçará esforço. Seu código deve distinguir entre esses dois grupos.
Passo a Passo: Chamada Durável
- Envie a solicitação. Se tiver sucesso, continue.
- Classifique o código de erro. Pode ser tentado novamente?
- Se possível: siga a tentativa novamente, aplique backoff exponencial + jitter, tente um número limitado de vezes (por exemplo, 5 no máximo).
- Se não tentar: Corrija (formato/chave) e pare; Não repita a mesma solicitação errada no loop.
- Considere desistir. Se ainda não tiver sucesso após n tentativas, mostre uma mensagem educada ao usuário e registre o evento (unidade de rastreamento 11).
# Chamada robusta pseudo-codedene = 0repeat: response = request_at() if response.success: retorna resposta se response.code em [429, 500, 529] e tenta < 5: wait = retry_after ?? (2^tente seg + jitter) dormir(espera); tente += 1; git novamente se response.code em [400, 401, 403, 404]: save_error(response); return "solicitação deve ser corrigida" return "erro permanente, tente mais tarde"
# Feedback educado para o usuário (quando as novas tentativas se esgotarem) "Estou ocupado agora, não consegui processar sua solicitação. Tente novamente em breve ou salvei sua solicitação, entrarei em contato com você quando estiver pronto."
Prompt fraco / Prompt forte (aqui: design de mensagem de erro)
# WEAK (exibe erro bruto para o usuário)"Erro 429: rate_limit_error"
# FORTE (amigável, tranquilizador, sugerindo ação) "Houve um congestionamento temporário no sistema. Recebemos sua solicitação com segurança e ela está sendo tentada novamente automaticamente. Se o resultado não aparecer em alguns segundos, você pode atualizar a página."
Revelar o erro técnico bruto ao usuário final prejudica a confiança e pode ser uma vulnerabilidade de segurança. Categorizar os erros internamente e passar ao usuário uma mensagem calma e orientada para a ação; basta escrever os detalhes técnicos para registro.
Três Mini Estojos
Caso 1 — Barco caiu em explosão de trânsito. Um bot de atendimento ao cliente recebeu 429 aumentos de tráfego no dia da campanha; Não houve nova tentativa no código, cada erro foi refletido diretamente para o usuário como um “erro”. Eles adicionaram retração exponencial + nova tentativa; com o mesmo tráfego, as solicitações passaram com um atraso de vários segundos, o usuário não viu nenhum erro.
Caso 2 — Tentando 400 no loop. Uma integração estava obtendo 404 devido a um ID de modelo inválido, mas estava tratando todos os erros como "transitórios" e tentando novamente em um loop infinito; A tora inchou e uma carga desnecessária foi criada. Eles adicionaram classificação de erro: 404 é considerado permanente, o loop é interrompido e o ID do modelo é corrigido. Lição: não tente todos os erros novamente.
Caso 3 — Gerenciando o limite pela frente. Um trabalho de enriquecimento de dados funcionava constantemente no limite 429. Eles seguiram o cabeçalho x-ratelimit-remaining e limitaram o tráfego de acordo com a cota. Então eles mantiveram um ritmo constante logo abaixo do limite, sem fazer nenhum 429s; O trabalho foi feito de forma mais previsível e rápida.
Erros comuns
- Aumentar a velocidade em 429: Piora a situação; Mude para recuar.
- Tentando novamente cada erro: 400/401/404 é permanente; Tentar novamente é um desperdício.
- Usando espera fixa: Cria uma colisão; Use exponencial + jitter.
- Ignorar 'nova tentativa após': É mais preciso cumprir o tempo especificado pelo provedor.
- Revelar o erro bruto ao usuário: abala a confiança, cria vulnerabilidades; Classifique por dentro.
- Tentativas ilimitadas: Defina um limite máximo (por exemplo, 5 tentativas); então desista graciosamente.
Mais profundo: filas, simultaneidade e disjuntores
A perseverança de um único desejo é o primeiro passo; A verdadeira maturidade é gerenciar um grande número de solicitações sem ultrapassar os limites. Três conceitos entram em jogo aqui.
Fila: você coloca as solicitações em uma fila para enviá-las em um ritmo controlado, e não imediatamente. O enfileiramento suaviza picos repentinos de tráfego: mesmo que 1.000 solicitações cheguem de uma vez, a fila irá liberá-las a uma taxa abaixo do limite. Dessa forma você evita o 429, então não precisa se preocupar em consertar.
Limite de simultaneidade: você limita quantas solicitações estão “no ar” ao mesmo tempo. Solicitações paralelas ilimitadas preenchem rapidamente os limites de RPM e TPM. Um teto de simultaneidade razoável (por exemplo, não mais que 10 solicitações simultâneas) mantém os limites e torna o sistema previsível.
Disjuntor: se o provedor continuar retornando 500/529, em vez de tentar obstinadamente cada solicitação, você “interrompe o circuito” por um tempo e rapidamente falha na solicitação, sem nunca enviá-la. Depois de uma espera, você liga o circuito novamente e tenta. Esse padrão evita que seu sistema trave no caso de uma falha temporária do provedor.
Juntos, esses três estabelecem resiliência em nível de sistema além da lógica de nova tentativa de uma única chamada. Em pequena escala, a nova tentativa automática do SDK é suficiente; À medida que a escala cresce, as filas, a simultaneidade e o disjuntor tornam-se indispensáveis. Todos eles têm o mesmo objetivo comum: refletir um problema temporário para o usuário não como uma falha, mas como um atraso invisível de alguns segundos.
Em resumo
429 retorna quando os limites de velocidade (RPM/ITPM/OTPM) são excedidos; Este é um erro temporário e será tentado novamente usando nova tentativa e espera exponencial + jitter. 500 e 529 também são provisórios; 400/401/403/404 é um problema de solicitação/identidade e não pode ser resolvido tentando novamente. Um fluxo robusto separa os erros nesses dois grupos, tenta um número limitado de vezes, monitora o limite pela frente e mostra mensagens calmas ao usuário.
Tarefa de aplicativo
Considere sua integração. (1) Liste os códigos de erro que você pode encontrar e separe-os em “repetidos/permanentes”. (2) Anote seu plano de pullback exponencial (retenção inicial, coeficiente, limite, jitter). (3) Especifique como usar o cabeçalho retry-after. (4) Escreva a mensagem educada a ser exibida ao usuário quando as novas tentativas se esgotarem.
lista de verificação
- [] Posso explicar os limites de RPM/ITPM/OTPM e 429.
- [] Posso aplicar a lógica de recuo exponencial + jitter + nova tentativa.
- [] Posso classificar os códigos de erro como repetíveis/permanentes.
- [ ] Sei que não devemos tentar todos os erros.
- [] Em vez de um erro bruto, posso mostrar ao usuário uma mensagem calma e orientada para a ação.