Gobernar Anthropic API versiones y encabezados beta en una puerta de enlace multiinquilino

Una puerta de enlace API compatible con Anthropic no debe tratar anthropic-version y anthropic-beta como encabezados de paso normales. Seleccionan el comportamiento del protocolo y las capacidades experimentales que pueden cambiar las reglas de validación, los bloques de respuesta, los eventos de transmisión, la disponibilidad, los precios y la contabilidad de caché.

El problema práctico es preservar el comportamiento nativo Claude sin permitir que los encabezados de solicitud de un inquilino omitan la política de la plataforma. La solución es hacer que la admisión del protocolo sea una decisión de primera clase en la puerta de enlace: autenticar a la persona que llama, resolver su política de versión, validar las funciones beta solicitadas, seleccionar una ruta compatible y registrar exactamente lo que se envió en sentido ascendente.

Definir el límite de la política

Hecho: Las solicitudes directas Claude API requieren un encabezado anthropic-version, aunque los SDK oficiales normalmente lo proporcionan. Anthropic funciones beta se solicitan a través de anthropic-beta o un parámetro beta específico de SDK.

Recomendación: Interprete ambos valores como capacidades solicitadas, no como instrucciones de enrutamiento confiables. Un cliente puede solicitar una versión o una versión beta, pero la puerta de enlace decide si esa combinación es compatible con el inquilino, la clave API, el modelo, la región y las credenciales ascendentes.

No elimines silenciosamente una versión beta no aprobada. Eso puede convertir una solicitud explícita en una llamada exitosa con una semántica diferente. Rechazarlo antes de enviarlo con un error de puerta de enlace estable que identifica la capacidad no compatible sin exponer las credenciales ascendentes ni los detalles de la ruta 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"
  }
}

Devuelve una respuesta 4xx para errores de admisión y reserva respuestas 5xx para errores de puerta de enlace o de flujo ascendente. Mantenga estable el esquema de error incluso si Anthropic cambia su propio formato de error.

Crear un registro de versiones y capacidades

Una cadena de versión con forma de fecha es fácil de validar sintácticamente pero imposible de controlar únicamente desde la sintaxis. La puerta de enlace necesita un registro que contenga las versiones y funciones beta que realmente ha probado.

Registros de versión

Cada registro de versión debe incluir:

• Identificador de versión canónica y estado del ciclo de vida: prueba, disponible, predeterminado, obsoleto o bloqueado.
• Campos de solicitud admitidos, bloqueos de contenido, motivos de detención, campos de uso y eventos de transmisión conocidos.
• Modelos compatibles, plataformas ascendentes, regiones y grupos de credenciales.
• Resultados de la fijación del contrato y fecha de la última prueba exitosa.
• Compatibilidad con el catálogo de precios y cualquier implicación conocida en la contabilidad de caché.
• Restricciones de adopción, fechas de desuso y directrices de reemplazo.

Registros beta

Las funciones beta necesitan registros separados porque su disponibilidad y riesgo operativo pueden diferir de la versión base API. Registre el nombre de la versión beta canónica, las versiones y modelos compatibles, las regiones permitidas, los campos de solicitud obligatorios, los posibles bloqueos de respuesta, los eventos de transmisión, el tratamiento de precios, la clase de límite de tarifa y el estado de implementación.

Modele esto como datos en lugar de condicionales de aplicación. Un evaluador de políticas puede entonces responder a una pregunta concreta: “¿Puede la clave K usar la versión V con el conjunto beta B en la ruta R?” El mismo catálogo puede admitir una puerta de enlace multimodelo API para equipos sin obligar a cada adaptador a implementar sus propias reglas de inquilino.

Proporcione a cada inquilino una política de versión explícita

Admite tres modos de política:

1. Fijado: El inquilino o la clave deben usar una versión exacta. Rechazar valores faltantes o diferentes.
2. Puerta de enlace actual: Un encabezado faltante se resuelve en el valor predeterminado probado de la puerta de enlace. Un valor de cliente explícito todavía está validado.
3. Rango aprobado: El cliente puede seleccionar de una lista finita de versiones probadas.

Evite interpretar "rango" como cada fecha entre dos puntos finales. Anthropic versiones son identificadores, no una secuencia continua de versiones semánticas. Almacene un conjunto explícito de valores admitidos.

Resuelva la versión efectiva antes de seleccionar una ruta ascendente:

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)

Mantenga separados los valores solicitados y efectivos. Pueden diferir cuando una política proporciona un valor predeterminado, pero un registro de auditoría debe hacer visible esa sustitución.

Analizar los encabezados beta estructuralmente

No autorice funciones beta con coincidencia de subcadenas o igualdad de cadenas sin formato. Analice el encabezado de acuerdo con la sintaxis aceptada por el upstream API, rechace las entradas duplicadas o con formato incorrecto según corresponda y compare los identificadores de características canónicas.

El orden canónico es útil para las claves de caché de políticas y las dimensiones de telemetría:

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

Conserve suficientes metadatos de solicitud para la depuración, pero no conserve los encabezados sin formato indefinidamente cuando los identificadores normalizados sean suficientes. Los registros de encabezado pueden contener metadatos de cliente innecesarios y almacenarlos aumenta el alcance de los controles de retención y acceso.

La autorización beta debe tener un ámbito de inquilino y, preferiblemente, un ámbito de clave. Una clave de desarrollo puede recibir una capacidad experimental sin otorgarla automáticamente a las cargas de trabajo de producción. Los cambios en las listas permitidas deben producir eventos de auditoría del plano de control con actor, motivo, estado anterior, estado nuevo y tiempo efectivo.

Admisión separada de la ruta

Una solicitud no se puede enrutar simplemente porque el nombre de su modelo existe. La elegibilidad de la ruta es la intersección de las capacidades del protocolo y la infraestructura:

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

Si ninguna ruta satisface el conjunto completo, falla antes de enviar la solicitud. No elimine las funciones beta para que una ruta sea elegible. No sustituya automáticamente otra versión a menos que la política del inquilino defina explícitamente ese comportamiento.

Esta separación es importante en puertas de enlace que agrupan credenciales, admiten claves proporcionadas por el cliente u operan en varias regiones. Dos rutas al mismo modelo pueden tener diferentes accesos a funciones, restricciones de residencia o límites de tarifas.

Conservar la semántica de respuesta nativa

Hecho: Anthropic Las respuestas de los mensajes pueden terminar con motivos que incluyen el uso de herramientas, límites de tokens, límites de ventanas de contexto, turnos pausados y rechazos. Las respuestas en streaming utilizan eventos nombrados enviados por el servidor y la guía de compatibilidad de Anthropic requiere que los clientes toleren nuevos tipos de eventos.

Recomendación: No colapse todos los estados terminales exitosos en "completado". Conserve el motivo de detención ascendente en la respuesta nativa y en la telemetría de la puerta de enlace. Es posible que las aplicaciones necesiten ejecutar una herramienta, continuar un giro en pausa, reducir el contexto o mostrar un rechazo.

El proxy de transmisión debe reconocer los eventos necesarios para la contabilidad y la gestión del ciclo de vida sin dejar de ser compatible con versiones futuras:

• Reenviar tipos de eventos desconocidos cuando la política del inquilino permita el paso nativo.
• Conservar el nombre del evento sin formato y la posición de la secuencia en los metadatos de diagnóstico delimitados.
• No utilice una enumeración exhaustiva que cierre la transmisión en un evento aditivo desconocido.
• Distinguir un evento de error ascendente de una desconexión de transporte y una cancelación de cliente.
• Finalizar el uso sólo desde campos autorizados; marcar transmisiones incompletas como provisionales cuando el uso final no esté disponible.

Si la puerta de enlace también expone un punto final con forma OpenAI, mantenga ese adaptador separado de la ruta nativa de Mensajes. La capa de compatibilidad OpenAI de Anthropic tiene limitaciones de funciones y campos documentados. Un sobre interno común puede ayudar con el enrutamiento, pero no debe descartar el orden de los bloques de contenido, los controles de caché, las firmas de pensamiento, el estado de las herramientas ni los motivos de detención específicos del proveedor.

Hacer que la contabilidad tenga en cuenta la versión

Hecho: El uso de la caché de solicitud separa los tokens de entrada ordinarios, los tokens de entrada de creación de caché y los tokens de entrada de lectura de caché. El consumo total de insumos debe tener en cuenta todas las categorías aplicables.

Un cambio de versión o beta puede alterar la elegibilidad de la caché, la representación del contenido o los campos de uso devueltos. Por lo tanto, cada evento de uso debe incluir:

• Versión API solicitada y efectiva.
• Conjuntos beta solicitados y admitidos.
• Inquilino, API clave, política, ruta, modelo, región e ID de solicitud ascendente.
• Estado, motivo de detención, estado de finalización de la transmisión y atribución de error.
• Categorías de tokens de entrada, salida, creación de caché y lectura de caché.
• Versión del catálogo de precios y estado de costos provisional o finalizado.

Estas dimensiones permiten que la IA unificada API facturación explique por qué solicitudes similares generaban costos diferentes. Evite la facturación a partir de un único recuento de tokens combinado cuando el proveedor expone categorías con diferentes tarifas.

Prueba antes de habilitar una versión o beta

Cree contratos para texto ordinario, transmisión de texto, llamadas a herramientas, resultados estructurados, rechazos, truncamiento de tokens, agotamiento de ventanas de contexto, turnos en pausa, almacenamiento en caché de avisos, solicitudes con formato incorrecto, límites de velocidad y errores a mitad de flujo.

Para cada partido, compara más de HTTP estados. Capture el tipo y orden de los bloques de contenido, el motivo de la detención, los identificadores y argumentos de las herramientas, la secuencia de eventos, la presencia del campo de uso, las categorías de caché y la forma del error. Almacene expectativas estructurales aprobadas en lugar de resultados exactos en prosa.

Utilice solicitudes ocultas solo cuando la ejecución duplicada sea segura. Las solicitudes con herramientas, efectos secundarios externos, datos confidenciales o costos de material pueden no ser adecuadas. Para esas cargas de trabajo, reproduzca accesorios desinfectados en un entorno controlado.

Predicción: Las nuevas versiones y funciones beta seguirán añadiendo variantes de respuesta y eventos. Una puerta de enlace diseñada en torno a registros de capacidad y análisis aditivo generalmente absorberá esos cambios con menos trabajo de emergencia que una construida alrededor de enumeraciones fijas y valores predeterminados globales.

Implementar y retirar capacidades de forma segura

Promover una capacidad a través de estados de prueba, internos, de participación voluntaria, canarios, disponibles, obsoletos y bloqueados. Durante el canarying, compare las distribuciones de estado, los motivos de detención, las secuencias de bloques de contenido, el comportamiento de las herramientas, los campos de uso, la latencia y los resultados de la caché. Defina umbrales de reversión antes de que comience el tráfico.

La jubilación debe realizarse por etapas:

1. Bloquear la adopción de nuevos inquilinos mientras continúan las asignaciones existentes.
2. Identifique los inquilinos afectados, las claves, los modelos y los patrones de solicitudes recientes.
3. Proporcione un informe de compatibilidad o un punto final de prueba para el reemplazo.
4. Avisar sobre solicitudes admitidas y publicar un corte firme.
5. Requerir excepciones explícitas con propietarios y fechas de vencimiento.
6. Bloquear la capacidad y conservar el registro de registro para auditoría histórica e interpretación de facturación.

La fijación aumenta la reproducibilidad pero expande la matriz de prueba. Una versión para toda la puerta de enlace reduce las variantes operativas pero une inquilinos no relacionados a un programa de migración. La transferencia beta amplia acelera el acceso a las funciones, pero debilita las garantías de costo, residencia y soporte. Para un servicio multiinquilino, la política explícita por inquilino suele ser el punto medio defendible.

Lista de verificación de implementación

• Requerir una política de versión para cada inquilino o clave API.
• Mantener registros de versión probada y capacidad beta.
• Rechazar capacidades con formato incorrecto, desconocidas o no autorizadas antes del envío.
• Seleccione rutas solo después de resolver la solicitud de protocolo completa.
• Conservar bloques de contenido nativo, motivos de detención, campos de uso y transmisiones.
• Reenviar eventos de flujo aditivo de forma segura y conservar sus nombres de eventos.
• Registrar los valores de protocolo solicitados y efectivos en eventos de uso y auditoría.
• Ejecutar elementos de contrato y canarios controlados antes de cambiar los valores predeterminados.
• Retirar capacidades antiguas mediante controles de adopción medidos, no reescrituras silenciosas.

La decisión de diseño clave es simple: los encabezados de versión y beta son entradas de políticas. Una vez que la puerta de enlace las admite, las enruta, las prueba y las mide como capacidades, la compatibilidad nativa API se vuelve gobernable sin pretender que el comportamiento experimental sean metadatos HTTP ordinarios.

Lecturas relacionadas

• contabilización del uso final, cancelaciones y respuestas de transmisión parcial