Motor de seleção de chave

Cada requisição que chega ao Load Balance percorre o mesmo caminho até uma chave concreta: valida a credencial, resolve a organização, tira da frente quem está em cooldown ou fora da janela de uso, escolhe pela estratégia do grupo e só então chama o provedor. Este guia mostra cada etapa e o que acontece quando a chave escolhida falha.

Pré-requisitos#

Antes de seguir o caminho inteiro, você precisa destes quatro fatos sobre a sua configuração.

O caminho de uma requisição#

Uma requisição atravessa oito etapas. Nenhuma delas fala com o provedor antes das três primeiras.

1. O proxy recebe

   Os quatro POST públicos são os dois com orgSlug e os dois legados sem ele. Os HEAD das mesmas rotas respondem 200 com corpo vazio: é o preflight que o cliente dispara contra a ANTHROPIC_BASE_URL antes da primeira chamada real.

   • POST /{orgSlug}/{customUrl}/v1/messages
   • POST /{orgSlug}/{customUrl}/v1/messages/count_tokens
   • POST /{customUrl}/v1/messages
   • POST /{customUrl}/v1/messages/count_tokens

2. A organização e a config são resolvidas

   Com orgSlug, o handler resolve a organização e depois a config da URL dentro dela. Organização inexistente responde igual a config inexistente, para a URL pública não enumerar organizações. Sem orgSlug — a rota legada, com data de remoção declarada para 2026-12-31 — o LB resolve só pelo customUrl e responde 409 pedindo a migração quando a URL existe em mais de uma organização.

3. A chave sk-lb- é validada

   A credencial é conferida antes de qualquer processamento. Um Bearer sk-ant-oat01-… é o OAuth do próprio cliente, não uma chave do LB, e não conta. Estas são as respostas que você pode receber:

   Situação	Status	O que o cliente recebe
   Contrato da empresa encerrado na Conta	403	permission_error com ORG_SUSPENDED
   Sem chave, chave inválida ou URL que você não vê	401	authentication_error
   Config inexistente	404	Custom URL config not found
   Config sem organização	403	o pool é por organização e não existe pool geral

4. A chave é removida dos headers

   stripProxyKeyHeaders tira a sk-lb- da request: a credencial do proxy nunca segue para o upstream, porque alguns caminhos repassam Authorization e x-api-key. Em seguida o chamador é registrado em memória — userApiKeyId quando a chave é pessoal, clientApiKeyId quando é de serviço.

5. Filtro de janela e de cooldown

   A seleção passa sempre por withoutLimitedAccounts, que tira as contas fora da janela de 5 h ou semanal, e depois pelo filtro de cooldown — antes de qualquer escolha. O snapshot vem do Redis com TTL de 15 s e sai ordenado por priority asc, lastUsed asc e id asc.

   Se todas as contas do grupo estiverem fora da janela, o LB não escolhe ninguém: responde 429 imediato com o Retry-After real do provedor, sem tocar no upstream, e o corpo diz qual janela estourou e quando a conta volta.

6. A chave é escolhida

   O handler principal chama o balancer na primeira linha útil. Se a chave escolhida tiver model próprio configurado, ele sobrescreve o modelo pedido pelo cliente, sempre.

7. A chamada sai e o failover assume

   Qualquer resposta fora da faixa 2xx é retentável entre chaves. O teto é o snapshot capturado do pool — uma tentativa por chave, sem reciclar — e o relógio é UPSTREAM_TIMEOUT, 180 s por dial.

8. A resposta volta para o cliente

   No caminho comum, o 2xx do upstream é repassado. Em streaming, o proxy segura o head até ler o primeiro frame SSE válido, com teto de 15 s, e só depois escreve o 200. Se todas as tentativas falharem, o cliente recebe 503 com corpo genérico overloaded_error.

As cinco estratégias#

A strategy do grupo decide como a lista de candidatas vira uma chave. São cinco valores, com round_robin como padrão.

O rating de rated combina TTFT, latência total e taxa de erro, e o peso do erro é grande porque, nos dados de produção citados, erro domina a latência como causa de requisição ruim. Uma chave sem amostra própria não entra em último lugar por falta de dados: ela entra com a mediana de TTFT do grupo. Se o grupo inteiro não tem nenhum TTFT conhecido, todas ficam iguais, o desempate estável preserva a ordem do snapshot e a corrida cai para o caminho único. Quem implementa o ranqueamento é keyRating.ts.

Cooldown e desativação#

Nem toda falha tira a chave de cena. O LB classifica o erro em três categorias e decide, a partir delas, o que fazer com a chave que respondeu:

O gatilho específico define a duração do cooldown:

O cooldown de 429 é proporcional ao tamanho do pool: acima de 100 chaves no snapshot ele cai para 10 s, porque com grupos de 400+ o valor fixo de 60 s fazia o failover percorrer a lista inteira em segundos. O estado mora em memória, com espelho best-effort no Redis, e o boot relê o Redis preservando o tempo que faltava do expiry absoluto — um cooldown de reset de janela, que dura horas, não pode virar 60 s. Quem implementa isso é cooldown.ts.

AUTO_DISABLE_ON_ERROR é o interruptor geral: ligado por padrão, desligado, nenhuma chave vira active=false mesmo em key_error — o proxy continua sanitizando a resposta, mas ninguém sai do rodízio.

Failover#

O gate é universal: qualquer status fora da faixa 2xx é retentável, no streaming e fora dele. O que muda é o teto e as regras.

Nada do upstream vaza. Todo non-2xx terminal vira 503 com corpo genérico; a única exceção é o corpo de mensagem do 429 e do 402, porque o cliente pode agir com ele. E, se os headers SSE já saíram, o status não muda mais: o proxy emite um frame event: error genérico e fecha o stream.

Quando todas estão frias#

Quando todas as candidatas estão em cooldown, o LB não desiste nem espera: pickEarliestCooldownExpiry devolve a chave cujo cooldown expira primeiro. É o último recurso, e vale tanto no caminho do grupo quanto no pool sem grupo.

Em empate de expiry a escolha é aleatória, e isso é deliberado — a implementação anterior devolvia sempre a primeira da lista, e o proxy martelava a mesma chave mesmo já sabendo que ela estava em cova.

Janela de uso esgotada é outro assunto: quando todas as contas do grupo estão fora da janela de 5 h ou semanal, o LB não desempata por cooldown, responde 429 com o Retry-After do provedor. O corte padrão é 95% de consumo e cada chave pode ter o seu próprio — leia Limites de uso.

Hedge e race#

hedge e race não mudam a chave primária: ela sai exatamente como em rated. O que muda é quando o resto entra. Antes de qualquer disparo, o portão barra nesta ordem e o primeiro motivo vence:

Endpoints diferentes mas equivalentes — mesmo provider, contas distintas — são justamente o caso de uso do hedge. O que decide a equivalência não é a string da URL: é o provider, que dá o formato da resposta, mais o authType, que dá os headers.

Passado o portão, só dois números entram na conta:

Duas chaves da mesma baseUrl nunca correm juntas, em nenhuma das duas estratégias. A comparação é estrita e dois baseUrl ausentes contam como a mesma URL. O motivo é de domínio: a cota de 429 é da conta/URL, não da chave, então duas chaves diferentes da mesma conta em cova levariam 429 juntas.

A vitória é decidida no primeiro chunk, nunca depois. O writeHead(200, 'text/event-stream') é ponto sem volta — trocar de upstream ali exigiria renormalizar o message.id e os índices SSE, e o cliente consome esse protocolo. Depois do 200 a requisição segue uma stream só até o fim, e a perdedora é abortada no dial em voo. Quando a reserva vence, o LB realoca a chave alvo para quem realmente atendeu: senão uso, cooldown e erro creditariam a perdedora.