Controle Anthropic API versões e cabeçalhos beta em um gateway multilocatário

Um gateway API compatível com Anthropic não deve tratar anthropic-version e anthropic-beta como cabeçalhos de passagem comuns. Eles selecionam comportamento de protocolo e recursos experimentais que podem alterar regras de validação, blocos de resposta, eventos de streaming, disponibilidade, preços e contabilidade de cache.

O problema prático é preservar o comportamento nativo Claude sem permitir que os cabeçalhos de solicitação de um locatário ignorem a política da plataforma. A solução é tornar a admissão do protocolo uma decisão de gateway de primeira classe: autenticar o chamador, resolver sua política de versão, validar os recursos beta solicitados, selecionar uma rota compatível e registrar exatamente o que foi enviado upstream.

Definir o limite da política

Fato: Solicitações diretas Claude API exigem um cabeçalho anthropic-version, embora os SDKs oficiais normalmente o forneçam. Anthropic recursos beta são solicitados por meio de anthropic-beta ou de um parâmetro beta específico de SDK.

Recomendação: interprete ambos os valores como recursos solicitados e não como instruções de roteamento confiáveis. Um cliente pode solicitar uma versão ou beta, mas o gateway decide se essa combinação é suportada para o locatário, API chave, modelo, região e credenciais upstream.

Não remova silenciosamente uma versão beta não aprovada. Isso pode transformar uma solicitação explícita em uma chamada bem-sucedida com semântica diferente. Rejeite-o antes do envio com um erro de gateway estável que identifica o recurso não suportado sem expor credenciais upstream ou detalhes de rota interna.

{
  "type": "gateway_policy_error",
  "code": "beta_not_allowed",
  "message": "The requested Anthropic beta is not enabled for this API key.",
  "details": {
    "beta": "example-beta-2026-01-01",
    "policy_id": "claude-production"
  }
}

Retorne uma resposta 4xx para falhas de admissão e reserve respostas 5xx para falhas de gateway ou upstream. Mantenha o esquema de erro estável mesmo se Anthropic alterar seu próprio formato de erro.

Crie um registro de versão e capacidade

Uma string de versão em forma de data é fácil de validar sintaticamente, mas impossível de controlar apenas pela sintaxe. O gateway precisa de um registro contendo as versões e os recursos beta que ele realmente testou.

Registros de versão

Cada registro de versão deve incluir:

• Identificador de versão canônica e estado do ciclo de vida: teste, disponível, padrão, obsoleto ou bloqueado.
• Campos de solicitação suportados, bloqueios de conteúdo, motivos de interrupção, campos de uso e eventos de streaming conhecidos.
• Modelos compatíveis, plataformas upstream, regiões e pools de credenciais.
• Resultados do contrato e data do último teste bem-sucedido.
• Compatibilidade do catálogo de preços e quaisquer implicações conhecidas de contabilidade de cache.
• Restrições de adoção, datas de suspensão de uso e orientações de substituição.

Registros beta

Os recursos beta precisam de registros separados porque sua disponibilidade e risco operacional podem ser diferentes da versão base API. Registre o nome beta canônico, versões e modelos compatíveis, regiões permitidas, campos de solicitação obrigatórios, possíveis blocos de resposta, eventos de streaming, tratamento de preços, classe de limite de taxa e estado de implementação.

Modele isso como dados em vez de condicionais de aplicativo. Um avaliador de políticas pode então responder a uma pergunta concreta: “A chave K pode usar a versão V com o conjunto beta B na rota R?” O mesmo catálogo pode suportar um gateway multimodelo API para equipes sem forçar cada adaptador a implementar suas próprias regras de locatário.

Dê a cada locatário uma política de versão explícita

Suporte a três modos de política:

1. Fixado: O locatário ou chave deve usar uma versão exata. Rejeite valores ausentes ou diferentes.
2. Gateway atual: Um cabeçalho ausente resolve o padrão testado do gateway. Um valor de cliente explícito ainda é validado.
3. Intervalo aprovado: O cliente pode selecionar em uma lista de permissões finita de versões testadas.

Evite interpretar “intervalo” como qualquer data entre dois pontos de extremidade. Anthropic versões são identificadores, não uma sequência contínua de versões semânticas. Armazene um conjunto explícito de valores admitidos.

Resolva a versão efetiva antes de selecionar uma rota upstream:

requested = parse_version_header(request)
policy = load_policy(tenant_id, api_key_id)
effective = resolve_version(requested, policy, registry)
betas = parse_and_canonicalize_betas(request)
admitted = authorize_betas(betas, policy, effective, registry)
route = select_compatible_route(model, region, effective, admitted)
dispatch(route, effective, admitted)

Mantenha os valores solicitados e efetivos separados. Eles podem ser diferentes quando uma política fornece um padrão, mas um registro de auditoria deve tornar essa substituição visível.

Analisar cabeçalhos beta estruturalmente

Não autorize recursos beta com correspondência de substring ou igualdade de string bruta. Analise o cabeçalho de acordo com a sintaxe aceita pelo upstream API, rejeite entradas malformadas ou duplicadas conforme apropriado e compare identificadores de recursos canônicos.

A ordenação canônica é útil para chaves de cache de políticas e dimensões de telemetria:

requested header: beta-b, beta-a
canonical policy set: [beta-a, beta-b]
upstream header: beta-b,beta-a  // serialized in accepted upstream syntax

Preserva metadados de solicitação suficientes para depuração, mas não retém cabeçalhos brutos indefinidamente quando identificadores normalizados são suficientes. Os registros de cabeçalho podem conter metadados de clientes desnecessários, e armazená-los aumenta o escopo da retenção e dos controles de acesso.

A autorização beta deve ter escopo de locatário e, de preferência, escopo de chave. Uma chave de desenvolvimento pode receber uma capacidade experimental sem concedê-la automaticamente às cargas de trabalho de produção. As alterações nas listas de permissões devem produzir eventos de auditoria no plano de controle com ator, motivo, estado anterior, novo estado e tempo efetivo.

Separar admissão do roteamento

Uma solicitação não é roteável apenas porque seu nome de modelo existe. A elegibilidade da rota é a interseção dos recursos de protocolo e infraestrutura:

eligible(route) =
  route.platform supports effective_version
  AND route.model supports every admitted_beta
  AND route.region permits every admitted_beta
  AND route.credentials are entitled to those capabilities
  AND route.pricing_catalog can account for the result

Se nenhuma rota satisfizer o conjunto completo, falhe antes de enviar a solicitação. Não abandone os recursos beta para tornar uma rota elegível. Não substitua automaticamente outra versão, a menos que a política do locatário defina explicitamente esse comportamento.

Essa separação é importante em gateways que agrupam credenciais, oferecem suporte a chaves fornecidas pelo cliente ou operam entre regiões. Duas rotas para o mesmo modelo podem ter acesso a recursos, restrições de residência ou limites de taxa diferentes.

Preservar a semântica da resposta nativa

Fato: Anthropic As respostas às mensagens podem terminar com motivos que incluem uso de ferramentas, limites de token, limites de janela de contexto, turnos pausados e recusas. As respostas de streaming usam eventos nomeados enviados pelo servidor, e a orientação de compatibilidade de Anthropic exige que os clientes tolerem novos tipos de eventos.

Recomendação: Não reduza todos os estados de terminal bem-sucedidos para “concluído”. Preserve o motivo da parada upstream na resposta nativa e na telemetria do gateway. Os aplicativos podem precisar executar uma ferramenta, continuar uma curva pausada, reduzir o contexto ou revelar uma recusa.

O proxy de fluxo deve reconhecer eventos necessários para contabilidade e gerenciamento do ciclo de vida, mantendo a compatibilidade futura:

• Encaminhe tipos de eventos desconhecidos quando a política do locatário permitir passagem nativa.
• Retenha o nome bruto do evento e a posição da sequência nos metadados de diagnóstico limitados.
• Não use uma enumeração exaustiva que feche o fluxo em um evento aditivo desconhecido.
• Distinguir um evento de erro upstream de uma desconexão de transporte e um cancelamento de cliente.
• Finalizar o uso somente de campos autorizados; marque streams incompletos como provisórios quando o uso final não estiver disponível.

Se o gateway também expor um endpoint em forma de OpenAI, mantenha esse adaptador separado do caminho nativo do Mensagens. A camada de compatibilidade OpenAI de Anthropic possui limitações de campos e recursos documentadas. Um envelope interno comum pode ajudar no roteamento, mas não deve descartar a ordem de bloqueio de conteúdo, controles de cache, assinaturas de pensamento, estado da ferramenta ou motivos de parada específicos do provedor.

Conheça a versão contábil

Fato: O uso do cache de prompt separa tokens de entrada comuns, tokens de entrada de criação de cache e tokens de entrada de leitura de cache. O consumo total de insumos deve considerar todas as categorias aplicáveis.

Uma alteração de versão ou beta pode alterar a elegibilidade do cache, a representação do conteúdo ou os campos de uso retornados. Portanto, todo evento de uso deve incluir:

• Versão API solicitada e efetiva.
• Conjuntos beta solicitados e admitidos.
• Locatário, API chave, política, rota, modelo, região e ID de solicitação upstream.
• Status, motivo da interrupção, estado de conclusão da transmissão e atribuição de erro.
• Categorias de entrada, saída, criação de cache e token de leitura de cache.
• Versão do catálogo de preços e estado de custo provisório ou finalizado.

Essas dimensões permitem que a IA unificada API faturamento explique por que solicitações semelhantes gerariam custos diferentes. Evite cobrar a partir de uma única contagem combinada de tokens quando o provedor expõe categorias com taxas diferentes.

Teste antes de ativar uma versão ou beta

Crie dispositivos de contrato para texto comum, streaming de texto, chamadas de ferramentas, saída estruturada, recusas, truncamento de token, esgotamento da janela de contexto, turnos pausados, cache de prompt, solicitações malformadas, limites de taxa e erros de fluxo intermediário.

Para cada fixture, compare mais de HTTP status. Capture o tipo e a ordem do bloco de conteúdo, o motivo da parada, os identificadores e argumentos da ferramenta, a sequência de eventos, a presença do campo de uso, as categorias de cache e o formato do erro. Armazene expectativas estruturais aprovadas em vez de resultados exatos em prosa.

Use solicitações shadow somente quando a execução duplicada for segura. Solicitações com ferramentas, efeitos colaterais externos, dados confidenciais ou custo de material podem ser inadequadas. Para essas cargas de trabalho, reproduza equipamentos higienizados em um ambiente controlado.

Predição: novas versões e recursos beta continuarão adicionando variantes de resposta e eventos. Um gateway projetado com base em registros de capacidade e análise aditiva geralmente absorverá essas alterações com menos trabalho emergencial do que um gateway criado com base em enumerações fixas e padrões globais.

Implante e desative recursos com segurança

Promover um recurso por meio de estados de teste, interno, opcional, canário, disponível, obsoleto e bloqueado. Durante o canarying, compare distribuições de status, motivos de parada, sequências de blocos de conteúdo, comportamento da ferramenta, campos de uso, latência e resultados de cache. Defina limites de reversão antes do início do tráfego.

A aposentadoria deve acontecer em etapas:

1. Bloqueie a adoção de novos locatários enquanto as atribuições existentes continuam.
2. Identifique locatários, chaves, modelos e padrões de solicitação recentes afetados.
3. Forneça um relatório de compatibilidade ou endpoint de teste para a substituição.
4. Avisar sobre solicitações admitidas e publicar um ponto de corte firme.
5. Exige exceções explícitas com proprietários e datas de expiração.
6. Bloqueie o recurso e retenha o registro do registro para auditoria histórica e interpretação de faturamento.

A fixação aumenta a reprodutibilidade, mas expande a matriz de teste. Uma versão para todo o gateway reduz as variantes operacionais, mas acopla locatários não relacionados a um cronograma de migração. A ampla passagem beta acelera o acesso aos recursos, mas enfraquece as garantias de custo, residência e suporte. Para um serviço multilocatário, a política explícita por locatário geralmente é o meio-termo defensável.

Lista de verificação de implementação

• Exige uma política de versão para cada locatário ou API chave.
• Mantenha registros de versão testada e capacidade beta.
• Rejeite recursos malformados, desconhecidos ou não autorizados antes do envio.
• Selecione rotas somente após resolver a solicitação de protocolo completa.
• Preserva blocos de conteúdo nativo, motivos de interrupção, campos de uso e fluxos.
• Encaminhe eventos de fluxo aditivos com segurança e retenha seus nomes de eventos.
• Registre valores de protocolo solicitados e efetivos em eventos de uso e auditoria.
• Execute dispositivos de contrato e canários controlados antes de alterar os padrões.
• Retire recursos antigos por meio de controles de adoção medidos, e não de reescritas silenciosas.

A principal decisão de design é simples: os cabeçalhos de versão e beta são entradas de política. Depois que o gateway os admite, roteia, testa e mede como capacidades, a compatibilidade nativa API torna-se governável sem fingir que o comportamento experimental é HTTP metadados comuns.

Leitura relacionada

• contabilização do uso final, cancelamentos e respostas parciais de streaming