Limites de uso

Acompanhe as janelas de 5 horas e semanais das contas de plano, ajuste o corte de cada conta na própria linha e entenda por que uma conta sai do rodízio sem ter dado erro nenhum.

Pré-requisitos#

Para ver e corrigir limites de uso você precisa de:

O que é uma conta de plano#

Conta de plano é uma assinatura upstream com limite de uso por janela — diferente de uma chave de API cobrada por token. O LB reconhece as quatro famílias pelo authType da chave ou, no caso do MiniMax, pelo provider:

Um 429 do provedor também alimenta o estado: o LB lê o reset no retry-after, nos headers ou no corpo e marca a conta fora até lá — quando o reset informado é maior que 90 s. Abaixo disso é um rate limit de minuto, não de janela, e quem cuida é o cooldown do motor.

Os headers de cada provedor, o formato e os quirks estão em Provedores upstream.

As duas janelas#

Toda conta de plano carrega duas janelas independentes — a de 5 horas e a semanal. Cada uma tem o percentual usado e o horário de reset, e o LB guarda os dois:

O estado dessas janelas não está no banco: vive no Redis, em duas chaves por conta — ulstate: com o % e o reset de cada janela (TTL de 8 dias) e ullimit: com o corte vigente (TTL até o reset). O caminho quente da seleção lê um mapa local de 5 s antes de ir ao Redis.

Dois detalhes de leitura: quando o Anthropic marca a janela como rejected no header de status, ela vale 100% independentemente do número; e a consulta das contas MiniMax e Muse roda também logo depois de um 429, para o % não ficar velho exatamente quando ele mais importa.

O corte#

O corte padrão é 95% de consumo. Cada chave pode ter o seu próprio no campo usageCutoffPct, no intervalo de 1 a 100 — valor fora do intervalo é ignorado e vale o padrão. Quando qualquer janela chega no corte da conta, ela sai do rodízio até o reset daquela janela; se as duas estouraram, vale o reset mais tardio. Reset que o provedor não informou vira 5 minutos: o LB revisa logo em seguida.

A volta é automática. Uma leitura abaixo do corte devolve ao rodízio a conta que estava fora por janela (5h ou 7d). Conta fora por 429 só sai no reset que o provedor informou — uma leitura boa não atalha o prazo que ele deu.

De quem é a janela#

O limite segue a conta upstream, não a chave. A identidade da conta é montada a partir dos metadados da chave:

Quando todas esgotam#

Antes de qualquer estratégia rodar, o pool tira da lista as contas limitadas. Quando todas as candidatas estão fora, o LB responde 429 imediato com o Retry-After do reset mais próximo entre elas — sem discar nenhum upstream, sem gastar tentativa:

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Todas as contas desta URL atingiram o limite semanal. A próxima volta em 2026-10-18 09:00 UTC (em 192 min)."
  }
}

O corpo diz qual janela estourou — de 5 horas, semanal ou do provedor, quando foi um 429 — e quando a próxima conta volta. Respeite o Retry-After: ele carrega o horário que o provedor anunciou, não um chute.

Ver e corrigir#

A tela Limites de uso (/app/usage-limits) é a sua janela de operação. Três rotas de painel a servem:

• GET /api/keys/usage
• GET /api/platform/keys/usage
• POST /api/platform/keys/:id/usage-limit/reset

A primeira rota traz as contas da organização da sessão; a segunda, as de todas as organizações — e só responde para a equipe da plataforma. A tela escolhe uma das duas pela sua função de agora e nunca mistura as duas.

1. Leia o painel

   A faixa do topo resume: quantas contas estão no rodízio, fora, perto do corte — alguma janela a 15 pontos do corte ou menos, 80% com o padrão de 95% — e qual é o próximo reset. A tela recarrega a cada 1 minuto, mas cada linha mostra a hora e a fonte da própria leitura: cabeçalho da resposta para Claude e Codex, consulta a cada 5 min para MiniMax e Muse, resposta 429 quando foi um 429 que travou. Filtre por marca, por estado e por nome; acima de 100 contas a lista virtualiza e só as linhas visíveis ficam no DOM. Chaves de plano desligadas não aparecem — desligada, a conta já está fora do rodízio.

2. Edite o corte na linha

   Cada conta mostra as duas barras de janela com a marca vertical do corte. O botão Editar abre um campo de 1 a 100 com Salvar e Voltar ao padrão (95%) — é o mesmo PUT /api/keys/:id da edição da chave, e quem pode editar a chave pode editar o corte. Na visão da plataforma, o corte só se edita nas contas da organização em que você está.

3. Solte uma conta presa

   A maioria dos casos se resolve sozinha no reset. O botão Liberar limite — só para a equipe da plataforma — existe para o caso em que o provedor zerou a janela antes do prazo: uma conta fora do rodízio não recebe tráfego e, para Claude e Codex, nenhum cabeçalho novo chega; o LB só a devolveria no reset anunciado. O POST /api/platform/keys/:id/usage-limit/reset limpa o limite, apaga as janelas pedidas (fiveHour, weekly, ou as duas) e tira a chave do cooldown curto. Se a conta ainda estiver estourada no provedor, o próprio limite volta no próximo 200.