Beheer Anthropic API versies en bètaheaders in een gateway voor meerdere tenants

Een Anthropic-compatibele API-gateway mag anthropic-version en anthropic-beta niet behandelen als gewone pass-through-headers. Ze selecteren protocolgedrag en experimentele mogelijkheden die validatieregels, responsblokken, streaminggebeurtenissen, beschikbaarheid, prijzen en cache-accounting kunnen veranderen.

Het praktische probleem is het behouden van native Claude gedrag zonder toe te staan dat de verzoekheaders van een tenant het platformbeleid omzeilen. De oplossing is om van protocoltoelating een eersteklas gateway-beslissing te maken: authenticeer de beller, bepaal het versiebeleid, valideer de gevraagde bètafuncties, selecteer een compatibele route en registreer precies wat upstream is verzonden.

Definieer de beleidsgrens

Feit: Directe Claude API verzoeken vereisen een anthropic-version header, hoewel officiële SDK's deze doorgaans leveren. Anthropic bètafuncties worden aangevraagd via anthropic-beta of een SDK-specifieke bètaparameter.

Aanbeveling: interpreteer beide waarden als gevraagde mogelijkheden, niet als vertrouwde routeringsinstructies. Een klant kan om een versie of bèta vragen, maar de gateway beslist of die combinatie wordt ondersteund voor de tenant, API sleutel, model, regio en upstream-inloggegevens.

Verwijder een niet-goedgekeurde bèta niet stilletjes. Dat kan een expliciet verzoek omzetten in een succesvolle oproep met verschillende semantiek. Weiger het vóór verzending met een stabiele gatewayfout die de niet-ondersteunde mogelijkheid identificeert zonder upstream-referenties of interne routedetails vrij te geven.

{
  "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"
  }
}

Retourneer een 4xx-reactie voor toegangsfouten en reserveer 5xx-reacties voor gateway- of upstream-fouten. Houd het foutschema stabiel, zelfs als Anthropic zijn eigen foutformaat verandert.

Een versie- en capaciteitsregister maken

Een datumvormige versietekenreeks is syntactisch eenvoudig te valideren, maar onmogelijk te beheren vanuit de syntaxis alleen. De gateway heeft een register nodig met de versies en bètafuncties die daadwerkelijk zijn getest.

Versierecords

Elk versierecord moet het volgende bevatten:

• Canonieke versie-ID en levenscyclusstatus: testen, beschikbaar, standaard, verouderd of geblokkeerd.
• Ondersteunde verzoekvelden, inhoudsblokkeringen, stopredenen, gebruiksvelden en bekende streaminggebeurtenissen.
• Compatibele modellen, upstream-platforms, regio's en referentiepools.
• Resultaten van contractovereenkomst en de datum van de laatste succesvolle test.
• Compatibiliteit met prijscatalogi en alle bekende implicaties voor cacheboekhouding.
• Aanvaardingsbeperkingen, beëindigingsdata en vervangingsrichtlijnen.

Bètarecords

Bètafuncties hebben afzonderlijke records nodig omdat hun beschikbaarheid en operationeel risico kunnen verschillen van de basisversie API. Noteer de canonieke bètanaam, compatibele versies en modellen, toegestane regio's, vereiste aanvraagvelden, mogelijke responsblokkeringen, streaminggebeurtenissen, prijsbehandeling, tarieflimietklasse en uitrolstatus.

Modeleer dit als gegevens in plaats van als applicatievoorwaarden. Een beleidsevaluator kan dan een concrete vraag beantwoorden: “Mag sleutel K versie V met bètaset B gebruiken op route R?” Dezelfde catalogus kan een multi-model API gateway voor teams ondersteunen zonder elke adapter te dwingen zijn eigen tenantregels te implementeren.

Geef elke tenant een expliciet versiebeleid

Ondersteuning van drie beleidsmodi:

1. Vastgezet: De tenant of sleutel moet één exacte versie gebruiken. Ontbrekende of verschillende waarden weigeren.
2. Gateway current: Een ontbrekende header leidt tot de geteste standaardwaarde van de gateway. Een expliciete klantwaarde wordt nog steeds gevalideerd.
3. Goedgekeurd bereik: De klant kan kiezen uit een eindige toelatingslijst met geteste versies.

Vermijd de interpretatie van 'bereik' als elke datum tussen twee eindpunten. Anthropic versies zijn ID's en geen continue reeks semantische versies. Sla een expliciete set toegestane waarden op.

Los de effectieve versie op voordat u een stroomopwaartse route selecteert:

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)

Houd de gevraagde en effectieve waarden gescheiden. Ze kunnen verschillen als een beleid een standaard levert, maar een auditrecord moet die vervanging zichtbaar maken.

Bètaheaders structureel parseren

Geef geen toestemming voor bètafuncties met subtekenreeksmatching of gelijkheid van onbewerkte tekenreeksen. Parseer de header volgens de syntaxis die door de upstream wordt geaccepteerd API, wijs onjuist opgemaakte of dubbele vermeldingen af, indien van toepassing, en vergelijk canonieke functie-ID's.

Canonieke volgorde is handig voor beleidscachesleutels en telemetriedimensies:

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

Bewaar voldoende metadata van verzoeken voor foutopsporing, maar bewaar onbewerkte headers niet voor onbepaalde tijd wanneer genormaliseerde ID's voldoende zijn. Headerlogboeken kunnen onnodige clientmetagegevens bevatten, en door deze op te slaan wordt de reikwijdte van de bewaar- en toegangscontrole vergroot.

Bèta-autorisatie moet tenantgericht zijn en bij voorkeur sleutelgericht. Een ontwikkelingssleutel kan een experimentele mogelijkheid krijgen zonder deze automatisch toe te kennen aan productieworkloads. Wijzigingen in toelatingslijsten moeten controlegebeurtenissen opleveren met actor, reden, vorige status, nieuwe status en effectieve tijd.

Aparte toegang en route

Een verzoek is niet routeerbaar louter omdat de modelnaam ervan bestaat. De geschiktheid van routes is het kruispunt van protocol- en infrastructuurmogelijkheden:

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

Als geen enkele route aan de volledige set voldoet, mislukt u voordat u het verzoek verzendt. Laat de bètafuncties niet vallen om een ​​route in aanmerking te laten komen. Vervang niet automatisch een andere versie, tenzij het tenantbeleid dat gedrag expliciet definieert.

Deze scheiding is van belang bij gateways die inloggegevens bundelen, door de klant geleverde sleutels ondersteunen of in verschillende regio's opereren. Twee routes naar hetzelfde model kunnen verschillende functietoegang, woonplaatsbeperkingen of tarieflimieten hebben.

Behoud de semantiek van de eigen reactie

Feit: Anthropic Reacties op berichten kunnen eindigen met redenen zoals toolgebruik, tokenlimieten, contextvensterlimieten, onderbroken beurten en weigeringen. Streamingreacties maken gebruik van benoemde, door de server verzonden gebeurtenissen, en de compatibiliteitsrichtlijnen van Anthropic vereisen dat clients nieuwe gebeurtenistypen tolereren.

Aanbeveling: Vouw niet alle succesvolle terminalstatussen samen in 'voltooid'. Behoud de upstream-stopreden in het systeem eigen antwoord en in gateway-telemetrie. Applicaties moeten mogelijk een tool uitvoeren, een onderbroken beurt voortzetten, de context beperken of een weigering naar voren brengen.

De streamproxy moet gebeurtenissen herkennen die nodig zijn voor boekhouding en levenscyclusbeheer, terwijl deze voorwaarts compatibel blijft:

• Stuur onbekende gebeurtenistypen door wanneer het beleid van de tenant native pass-through toestaat.
• Bewaar de onbewerkte gebeurtenisnaam en reekspositie in begrensde diagnostische metadata.
• Gebruik geen uitputtende opsomming die de stream sluit bij een onbekende additieve gebeurtenis.
• Onderscheid een upstream-foutgebeurtenis van een transportverbinding en een clientannulering.
• Voltooi het gebruik alleen van gezaghebbende velden; markeer onvolledige streams als voorlopig wanneer het uiteindelijke gebruik niet beschikbaar is.

Als de gateway ook een OpenAI-vormig eindpunt blootlegt, houd die adapter dan gescheiden van het oorspronkelijke berichtenpad. De OpenAI-compatibiliteitslaag van Anthropic heeft gedocumenteerde veld- en functiebeperkingen. Een gemeenschappelijke interne envelop kan helpen bij het routeren, maar mag de volgorde van inhoudsblokken, cachecontroles, denkhandtekeningen, toolstatus of providerspecifieke stopredenen niet negeren.

Maak de boekhouding versiebewust

Feit: Bij gebruik van promptcache worden gewone invoertokens, invoertokens voor het maken van caches en invoertokens voor lezen in de cache gescheiden. Het totale inputverbruik moet rekening houden met alle toepasselijke categorieën.

Een versie- of bètawijziging kan de geschiktheid van de cache, de weergave van de inhoud of de geretourneerde gebruiksvelden wijzigen. Daarom moet elke gebruiksgebeurtenis het volgende bevatten:

• Aangevraagde en effectieve API versie.
• Aangevraagde en toegelaten bètasets.
• Tenant, API sleutel, beleid, route, model, regio en upstream-verzoek-ID.
• Status, stopreden, voltooiingsstatus van de stream en foutattributie.
• Tokencategorieën voor invoer, uitvoer, cache maken en lezen in cache.
• Prijscatalogusversie en voorlopige of definitieve kostenstatus.

Dankzij deze dimensies kan unified AI API billing verklaren waarom soortgelijke verzoeken anders tot verschillende kosten zouden leiden. Vermijd facturering op basis van één gecombineerd aantal tokens wanneer de provider categorieën met verschillende tarieven openbaar maakt.

Test voordat u een versie of bèta inschakelt

Maak contractoverzichten voor gewone tekst, streaming tekst, toolaanroepen, gestructureerde uitvoer, weigeringen, tokenafkapping, uitputting van contextvensters, gepauzeerde beurten, promptcaching, verkeerd opgemaakte verzoeken, snelheidslimieten en midstream-fouten.

Vergelijk voor elk armatuur meer dan HTTP status. Leg het type en de volgorde van inhoudsblokken vast, stopreden, tool-ID's en -argumenten, gebeurtenisvolgorde, aanwezigheid van gebruiksvelden, cachecategorieën en foutvorm. Bewaar goedgekeurde structurele verwachtingen in plaats van exacte prozauitvoer.

Gebruik schaduwverzoeken alleen als dubbele uitvoering veilig is. Verzoeken met tools, externe bijwerkingen, gevoelige gegevens of materiaalkosten kunnen ongeschikt zijn. Voor deze werklasten kun je opgeschoonde armaturen opnieuw afspelen in een gecontroleerde omgeving.

Voorspelling: Nieuwe versies en bètafuncties zullen antwoordvarianten en gebeurtenissen blijven toevoegen. Een gateway die is ontworpen rond capaciteitsrecords en additieve parsering absorbeert deze wijzigingen doorgaans met minder noodwerk dan een gateway die is gebouwd rond vaste enums en globale standaardwaarden.

Mogelijkheid veilig uitrollen en buiten gebruik stellen

Promoot een mogelijkheid via test-, interne, opt-in-, canary-, beschikbare, verouderde en geblokkeerde statussen. Tijdens canarying kunt u statusverdelingen, stopredenen, inhoudblokreeksen, toolgedrag, gebruiksvelden, latentie en cacheresultaten vergelijken. Definieer drempelwaarden voor terugdraaien voordat het verkeer begint.

Pensioen moet in fasen gebeuren:

1. Blokkeer de adoptie van nieuwe tenants terwijl bestaande toewijzingen doorgaan.
2. Identificeer de getroffen tenants, sleutels, modellen en recente verzoekpatronen.
3. Geef een compatibiliteitsrapport of testeindpunt op voor de vervanging.
4. Waarschuw voor toegelaten verzoeken en publiceer een definitieve afsluiting.
5. Vereist expliciete uitzonderingen met eigenaren en vervaldatums.
6. Blokkeer de mogelijkheid en bewaar de registerrecord voor historische audit- en factureringsinterpretatie.

Vastzetten verhoogt de reproduceerbaarheid maar breidt de testmatrix uit. Een gateway-brede versie vermindert operationele varianten, maar koppelt niet-gerelateerde tenants aan één migratieschema. Brede bèta-passthrough versnelt de toegang tot functies, maar verzwakt de garanties op het gebied van kosten, ingezetenschap en ondersteuning. Voor een service met meerdere tenants is een expliciet beleid per tenant meestal de verdedigbare middenweg.

Implementatiechecklist

• Vereist een versiebeleid voor elke tenant of API sleutel.
• Geteste versie- en bètacapaciteitsrecords bijhouden.
• Weiger onjuist opgemaakte, onbekende of ongeautoriseerde mogelijkheden vóór verzending.
• Selecteer routes pas nadat het volledige protocolverzoek is opgelost.
• Behoud native inhoudsblokken, stop redenen, gebruiksvelden en streams.
• Stuur additieve streamgebeurtenissen veilig door en behoud hun gebeurtenisnamen.
• Registreer de gevraagde en effectieve protocolwaarden voor gebruiks- en auditgebeurtenissen.
• Voer contractwedstrijden en gecontroleerde kanaries uit voordat u de standaardinstellingen wijzigt.
• Oude mogelijkheden buiten gebruik stellen door middel van maatregelen voor afgemeten adoptie, en niet door stille herschrijvingen.

De belangrijkste ontwerpbeslissing is eenvoudig: versie- en bètaheaders zijn beleidsinvoer. Zodra de gateway ze als mogelijkheden toestaat, routeert, test en meet, wordt native API compatibiliteit regelbaar zonder te doen alsof experimenteel gedrag gewone HTTP metadata is.

Gerelateerd lezen

• rekening houdend met eindgebruik, annuleringen en gedeeltelijke streamingreacties