Hermify
Voltar ao Blog
HermesOpenRouterTroubleshootingModels

Erros de rate limit da OpenRouter no Hermes Agent

Hermes Agent batendo em 429 da OpenRouter ou um 402 no meio da conversa? As causas concretas, a matemática dos retries e a cadeia de fallback que mantém tudo no ar.

Por Hermify Team||9 min de leitura
Terminal mostrando um erro 429 Too Many Requests da OpenRouter ao lado de um processo Hermes Agent em execução

Seu agente parou no meio da conversa

Você está no terceiro turno de um papo com Hermes Agent que finalmente estava útil quando a resposta volta vazia, e o log mostra uma linha vermelha: 429 Too Many Requests. Ou pior, um 402 Payment Required porque o modelo recusou a requisição de cara. O agente que estava fino uma hora atrás agora é uma parede de erros de retry, e você está a uma sessão de debug de trocar de provedor.

Os códigos de erro da OpenRouter são precisos assim que você sabe o que cada um significa. 429 é rate limit e vem de três lugares diferentes. 402 é esgotamento de crédito e não se comporta em nada como 429. 503 é indisponibilidade do provedor upstream e é o único que dá para automatizar sem dor. Cada um tem uma correção específica, e o array models do Hermes Agent transforma a maioria em não-evento.

Lendo os códigos de erro da OpenRouter de relance

Antes de mexer na config, entenda o que a API está te dizendo. A OpenRouter documenta esses códigos de forma explícita e os números importam.

Código Significado Retry?
402 Créditos insuficientes ou cota diária do modelo gratuito esgotada Não, recarregue ou troque de modelo
403 Falha de permissão, bloqueio de moderação ou guardrail Não, a requisição fica recusada
429 Limite de taxa atingido (OpenRouter ou provedor upstream) Sim, respeite Retry-After
503 Nenhum provedor disponível agora para o modelo pedido Sim, ou caia em outro modelo

Um 429 e um 402 parecem iguais no terminal, mas exigem respostas opostas. Retentar um 402 em loop só queima seu orçamento de retry enquanto o saldo continua zerado. Retentar um 429 com juízo é o jogo inteiro.

O outro detalhe que vale ler é error.metadata.provider_code. Quando um 429 vem do provedor upstream que atende sua requisição (Anthropic, DeepSeek, OpenAI, Groq), a OpenRouter encaminha o código de erro original desse provedor nesse campo. Isso distingue um limite de plataforma da OpenRouter de um limite do tenant upstream, e cada um tem correção diferente.

Causa 1: teto diário do plano gratuito da OpenRouter

Sintoma: ontem funcionou, hoje de manhã funcionou, e agora toda requisição volta 429 mesmo com pouquíssimo tráfego. Costuma aparecer depois de uns 20 minutos de sessão normal do Hermes.

O que está acontecendo: o plano gratuito da OpenRouter permite 20 requisições por minuto contra modelos gratuitos, com teto de 50 por dia. Uma compra única de US$ 10 em créditos sobe o piso diário de 50 para 1.000 permanentemente. O loop de ferramentas do Hermes Agent (um turno é uma chamada de API, mais os retries) esgota um dia de 50 requisições dentro de uma única conversa média.

Confira primeiro: confirme que o modelo na sua config é do plano gratuito. Modelos gratuitos na OpenRouter carregam o sufixo :free no slug (deepseek/deepseek-v4-flash:free). Se sua linha model: termina em :free, esse teto se aplica.

Correção imediata: adicione US$ 10 em créditos no painel da OpenRouter. O teto diário pula para 1.000/dia para sempre, suficiente para um usuário normal do Hermes.

Correção de fundo: pare de rotear tráfego de produção por um modelo gratuito. Modelos gratuitos são para avaliação, não para um agente rodando. Troque para o mesmo modelo sem :free e pague a tarifa (DeepSeek V4-Flash sem sufixo custa US$ 0,14/M input, então um dia de uso do Hermes são centavos). A matemática completa dos preços está em o modelo mais barato da OpenRouter para Hermes Agent.

Causa 2: rate limit do provedor upstream (429 com provider_code)

Sintoma: você está num modelo pago, os créditos estão saudáveis, mas ainda assim leva 429 quando o Hermes fica ocupado. O corpo da resposta contém error.metadata.provider_code com um valor tipo rate_limit_exceeded ou insufficient_quota.

O que está acontecendo: a OpenRouter em si não impõe teto duro em modelos pagos, mas o provedor upstream sim. Anthropic, OpenAI e DeepSeek aplicam limites por conta com base no seu tier. Quando a OpenRouter roteia sua requisição para o upstream, o upstream recusa e a OpenRouter repassa a recusa como 429.

Diagnóstico:

  • Leia error.metadata.provider_code. Se disser rate_limit_exceeded, é este caso.
  • Verifique se a requisição bateu num pico (dezenas de turnos numa janela curta) ou em regime estável. Picos disparam limites por minuto, tráfego sustentado dispara os diários.
  • Confirme o modelo. Alguns modelos são roteados por um único provedor com teto apertado (modelos com marca Anthropic via OpenRouter compartilham os limites da própria conta da Anthropic).

Correções:

  • Respeite o header Retry-After da resposta. Tanto em 429 quanto em 503, a OpenRouter devolve um Retry-After em segundos. Espere esse tempo antes de retentar e, se ainda falhar, use backoff exponencial com jitter.
  • Configure uma cadeia de modelos de fallback (Causa 4 mais abaixo). O array de modelos é a correção mais eficaz aqui, porque o Hermes retenta automaticamente com o próximo modelo em vez de derrubar o turno.
  • Se um modelo específico não para de tropeçar, considere BYOK. Trazer sua própria chave de Anthropic ou OpenAI para a OpenRouter te dá os limites da sua própria conta upstream em vez de compartilhar o pool da OpenRouter.

Causa 3: os créditos acabaram no meio da conversa (402)

Sintoma: o agente aguentou os primeiros 30 turnos e agora toda requisição volta 402 insufficient_credits. O painel da OpenRouter mostra saldo de US$ 0,00.

O que está acontecendo: OpenRouter é saldo pré-pago, não fatura mensal. Assim que o saldo chega a zero, cada requisição é recusada com 402 até você recarregar. Usuários de modelo gratuito também veem 402 quando a cota gratuita do dia esgota (usa o mesmo código do fim de crédito pago, o que confunde, mas é consistente com a documentação da OpenRouter).

Correções:

  • Ative o auto-topup no painel da OpenRouter. Defina um limite (ex.: adicionar US$ 10 automaticamente quando o saldo cair abaixo de US$ 2). É a única correção que evita 402s em produção.
  • Defina um teto de gasto mensal no mesmo painel para o auto-topup não virar silenciosamente um mês ruim.
  • Se você está usando BYOK no tier Starter da Hermify, a chave da OpenRouter é sua e o saldo é seu para recarregar. A Hermify não adianta créditos por você.

Não implemente retries client-side para o 402. Cada retry é outra chamada de API que também volta 402, e a OpenRouter as conta contra seu rate limit mesmo quando falham.

Causa 4: não há cadeia de fallback configurada

Sintoma: qualquer indisponibilidade de um único modelo em qualquer ponto da rede de provedores da OpenRouter derruba seu agente completamente até o upstream se recuperar. Um 429 no modelo primário vira uma sessão quebrada.

O que está acontecendo: por padrão, o Hermes Agent manda uma requisição nomeando exatamente um modelo. Se esse modelo está com rate limit ou se todos os provedores dele estão no teto, a OpenRouter devolve o erro e o Hermes não tem para onde rotear. Você leva uma linha vermelha no log e o turno se perde.

A correção é o parâmetro models da OpenRouter, que aceita um array de modelos em ordem de prioridade. Se o primeiro devolve erro, a OpenRouter tenta o próximo, depois o próximo. Só quando o último também falha o erro volta para o Hermes.

Configure uma cadeia de 3 modelos de fallback em ~/.hermes/config.yaml. Um exemplo com forma de produção:

provider: openrouter
openrouter_api_key: sk-or-sua-chave-aqui
model: deepseek/deepseek-v4-pro
fallback_models:
  - anthropic/claude-haiku-4-5
  - google/gemini-2.5-flash
  - openai/gpt-4.1-mini

Essa cadeia te dá um primário forte (DeepSeek V4-Pro para raciocínio pesado em ferramentas), um secundário rápido e confiável de outra família de provedores e mais dois fallbacks em nuvens diferentes. Se a DeepSeek estiver degradada, a requisição vai para a Anthropic sem perder o turno. O post sobre o melhor provedor de modelos para Hermes Agent tem mais sobre os trade-offs entre famílias de provedores.

Regras de bolso para a cadeia:

  • Escolha modelos de famílias de provedores diferentes. Dois modelos da OpenAI caem juntos durante um incidente da OpenAI.
  • Ordene por qualidade primeiro, custo depois. A cadeia roda de cima para baixo e para no primeiro sucesso.
  • Mantenha entre 3 e 5 entradas. Dez fallbacks são dez retries sequenciais num dia ruim, o que é pior do que uma falha barulhenta.

Causa 5: tempestades de retry vindas do próprio Hermes

Sintoma: um único 429 vira centenas de requisições falhas no log, cada uma piorando o rate limit. O painel mostra um pico de requisições bem na hora em que quebrou.

O que está acontecendo: sem backoff exponencial, o Hermes retenta imediatamente uma requisição com rate limit, o que dispara o mesmo limite de novo, o que retenta de novo. O loop de retry transforma um erro recuperável numa queda auto-infligida. É a versão OpenRouter do clássico stampede de rate limit no lado cliente.

Correções:

  • Verifique se o Hermes está respeitando Retry-After. Versões modernas fazem isso por padrão; forks antigos podem não fazer. Confira a versão com hermes --version e atualize se estiver atrasado.
  • Configure uma fila com token bucket se você roda Hermes contra uma conta single-tenant. Forçar um gap mínimo de 3 segundos entre requisições elimina 429s de vez num setup de um usuário só.
  • Se o loop de retry já aconteceu, espere 5 minutos antes de reiniciar o agente. O rate limiter da OpenRouter tem uma janela de aquecimento, e restarts imediatos estendem o bloqueio.

O mesmo padrão de falha aparece em qualquer integração de API de alto volume, não só na OpenRouter. Veja debugging e observabilidade do Hermes Agent para as convenções de log que tornam isso diagnosticável.

Quando parar de babá do provedor

Cada correção deste post é um pequeno ajuste em como a camada de modelos está cabeada. O array models mais o auto-topup na OpenRouter cobrem 90% do que quebra. O resto é paciência e o tratamento correto de Retry-After.

O que queima tempo é descobrir tudo isso na tarde em que seu agente para no meio de um projeto e você percebe então que o teto do plano gratuito bateu, a cadeia de fallback nunca foi configurada e o loop de retry transformou um soluço pequeno numa queda de duas horas. Se você preferir não aprender a taxonomia de erros da OpenRouter no braço, a Hermify roda um Hermes Agent gerenciado no Telegram com a cadeia de fallback já cabeada, uma chave da OpenRouter medida (você traz a sua ou usa a nossa) e um piso de topup que te mantém acima de zero. Sua chave BYOK continua sendo sua, mas você deixa de ser o de plantão dos 429.

Comece com a Hermify e pule o postmortem da tempestade de retries.

Sources

Lance seu próprio agente Hermes

Traga sua chave de API, conecte o Telegram e tenha um agente de IA que evolui sozinho no ar em 60 segundos.

Começar agora