Configurações de roteamento

Retry, fallback, load balance e cache — decididos por configuração, nunca por código do cliente.

Uma config descreve para onde a chamada vai e o que fazer quando ela falha. Ela é resolvida a cada requisição, nesta ordem de precedência: o cabeçalho x-portkey-config vence a config padrão da chave, que vence "nenhuma config". Um id que não existe nesta organização recusa 400 config_invalido — nunca cai calado no padrão.

A forma

json

{
  "retry": {
    "attempts": 3,
    "on_status_codes": [429, 500, 502, 503, 504, 529],
    "use_retry_after_headers": false
  },
  "strategy": { "mode": "fallback", "on_status_codes": [] },
  "targets": [
    { "model": "gpt-4o-mini" },
    { "model": "claude-3-5-haiku" }
  ],
  "cache": { "mode": "simple", "max_age": 86400 }
}

Retry

attempts: inteiro entre 1 e 5.
on_status_codes: quais status disparam a retentativa. Omitido, vale o padrão [429, 500, 502, 503, 504, 529].
use_retry_after_headers: respeita o Retry-After do provedor em vez do backoff próprio. Falso por padrão.

Fallback e load balance

strategy.mode aceita dois valores, e a lista de targets muda de significado conforme ele:

Os dois modos de estratégia
Modo	Como os targets são usados
`fallback`	Em ORDEM: o primeiro target atende; falhando num status de `strategy.on_status_codes`, o próximo assume. `weight` não existe neste modo — um peso aqui é recusado.
`loadbalance`	Sorteio ponderado por `weight` (padrão 1, materializado só neste modo). Distribui carga entre integrações equivalentes.

Um target aponta para um modelo do catálogo da própria organização; modelo inexistente e modelo de outra organização recebem a mesma recusa — idêntica de propósito, para não revelar o que existe na organização de outra pessoa.

Quantas tentativas o roteamento consumiu sai no cabeçalho x-avalon-retry-attempt-count — presente só quando havia config de roteamento. As tentativas não-finais viram linhas próprias na trilha: a cadeia inteira é auditável, não só o passo que deu certo.

Cache de respostas

cache.mode aceita hoje um único valor: simple — chave derivada do corpo da requisição, com max_age em segundos (padrão 86400, ou 24 horas; precisa ser inteiro positivo). O status sai em x-portkey-cache-status: HIT, MISS, REFRESH ou DISABLED — ausente quando não havia config de cache. Mandar x-portkey-cache-force-refresh (a presença basta, o valor não importa) ignora a entrada e a regrava.

Cache semântico (por similaridade de embedding) não existe: uma config pedindo semantic é recusada. É uma limitação nomeada, não um bug — o índice vetorial que ele exigiria é trabalho de outra onda.