Claude Code gateway compatibility guide

• API formats and the endpoints to serve for each
• Client behavior by connection method: how model IDs, anthropic-beta values, request fields, and defaults differ between the formats and a Claude apps gateway sign-in
• Request headers: which must reach the upstream and which your gateway can consume
• Response headers: what to return so stall detection, retries, and usage limit display work
• The system prompt attribution block and how it interacts with prompt caching
• Feature pass-through: what breaks when headers or body fields are stripped
• Model discovery

• Forward unchanged: pass it to the upstream byte-for-byte
• Consume: the gateway may read it for routing, attribution, or tracing and need not forward it

​

API formats

​

Foundry and Claude Platform on AWS

​

Optional endpoints and startup traffic

• Inference requests post to /v1/messages?beta=true
• The Google Cloud’s Agent Platform method suffixes attach to the publisher model path, as in /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict

​

Streaming

• If your gateway buffers a response until it is complete, Claude Code stalls.
• Claude Code expects each response’s full event sequence, in order, through the final message_delta and message_stop events. If the body ends cleanly after a content block has started but before that final message_delta, Claude Code treats the response as a dropped connection. The response above may be incomplete describes what the user sees then, and Automatic retries says when Claude Code re-issues the request instead.
• When an Amazon Bedrock guardrail blocks a reply, the events Bedrock sends can reference a content block whose content_block_stop already arrived, and Claude Code relies on receiving them as sent. AWS Guardrails describes how that reply ends.
• Claude Code aborts a streaming response once no bytes reach it for longer than its streaming idle timeout. During a long thinking pause, the upstream’s SSE ping events can be the only bytes on the stream, so a gateway that strips or buffers them can trip that timeout partway through a response. A gateway that translates from an upstream without pings, such as Amazon Bedrock’s binary event stream, has the same gap unless it emits its own ping events.
• On the Amazon Bedrock InvokeModel format, Claude Code reads the /model/{model}/invoke-with-response-stream response as the binary application/vnd.amazon.eventstream body Bedrock returns, and can’t parse it once a gateway converts it to server-sent events or rewrites that Content-Type header. Streaming errors behind a gateway or proxy describes what the user sees then.

​

Format mismatch with the upstream

• When the client speaks the Amazon Bedrock or Google Cloud’s Agent Platform format, Claude Code sends only the subset of its full capability set that those providers accept
• When the client speaks the Anthropic Messages format, Claude Code sends the full set, even if your gateway forwards to an Amazon Bedrock or Google Cloud’s Agent Platform upstream

​

How the connection method changes client behavior

• Amazon Bedrock or Agent Platform format: the developer sets CLAUDE_CODE_USE_BEDROCK=1 with ANTHROPIC_BEDROCK_BASE_URL, or CLAUDE_CODE_USE_VERTEX=1 with ANTHROPIC_VERTEX_BASE_URL, pointing at your gateway. Claude Code uses that provider’s model IDs, request fields, and defaults.
• Anthropic Messages format: the developer sets ANTHROPIC_BASE_URL to your gateway. Claude Code treats the gateway as the Claude API and can’t tell which upstream you forward to.
• Claude apps gateway sign-in: the developer signs in to a Claude apps gateway. That gateway speaks the Anthropic Messages format but can route to any upstream, so Claude Code sends only the anthropic-beta values and model-capability assumptions that Amazon Bedrock and Agent Platform also accept.

​

Requests and defaults by connection method

​

Settings for unrecognized model IDs

• Context window: Claude Code assumes 200K, or 1M when the ID carries [1m]. To declare the real window, see Correct the window for a gateway or custom model ID
• Capabilities: to give a gateway alias the capabilities of the model behind it, map that model’s Anthropic ID to your alias with a modelOverrides entry in the settings you distribute. For where the ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES variables apply, see feature pass-through

​

Request headers

​

Gateway hint headers

• Direct connection to the Anthropic API: sent by default
• Custom base URL: off by default, because a proxy that rejects unknown headers would fail the request. To receive them, set CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 for your developers, for example in the env block of managed settings
• Any other backend, including Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, and Claude Platform on AWS: sent only when CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 is set

• Entries: one per tool call that ran, in the order its result was collected, in whole milliseconds
• Cap: Claude Code sends at most 32 entries and 4 KB, keeping the first entries
• Encoding: tool names are percent-encoded, covering %, ;, =, comma, space, and any character outside printable ASCII
• Parsing: split on ;, then on =, and decode each name
• Absence: compaction calls, side requests, and the first request of a new prompt never carry it. Don’t read a missing header as a turn that ran no tools
• Times: each one excludes permission prompts and hooks, and parallel tool calls each report their own time, so the entries don’t add up to the gap between requests

​

Forward as open lists

​

Response headers

​

System prompt attribution block

• Forward the system array exactly as received, keeping the block first: prepending another system block, reordering the array, or converting it to a single string defeats the strip, and the block then reaches the model and the prompt cache key.
• Keep the block in its own array entry: the endpoint treats a merged block that starts with the attribution header as attribution in its entirety and drops everything merged into it, including the rest of the system prompt.
• If your gateway must reshape system content, set CLAUDE_CODE_ATTRIBUTION_HEADER=0 so Claude Code omits the block. Anthropic and the cloud providers’ Claude endpoints read the block for attribution, so omit it at the client rather than stripping or moving it in the gateway.

• The requests go to api.anthropic.com, with ANTHROPIC_BASE_URL unset or naming that host and no third-party provider selected.
• The active credential isn’t an Anthropic profile or federation credential.

• Implements a prompt cache keyed on the request body.
• Forwards requests to a third-party provider such as Amazon Bedrock, Microsoft Foundry, or Google Cloud’s Agent Platform, in the Anthropic Messages format or the provider’s own, where the changing prefix reduces prompt-cache reuse on that provider.

​

Feature pass-through

​

Beta header and body field pairs

​

Automatic retry and error forwarding

• When a 400 says the thinking.type value enabled or adaptive isn’t supported, Claude Code retries once with the other type and keeps the thinking field. Later requests to that model keep the switched type until Claude Code exits. Before v2.1.121, Claude Code didn’t retry, so thinking.type.enabled is not supported reached the developer
• When the upstream rejects a role: "system" entry inside messages, Claude Code retries once without those mid-conversation system messages and carries their text in user messages instead. Later requests in the conversation keep that shape until the developer runs /clear or the conversation compacts
• When the upstream rejects only the cache_control marker on a mid-conversation system message, Claude Code keeps the system messages and retries once with the marker moved. The marker goes on the last entry in messages that isn’t a system message, in that retry and in later requests until Claude Code exits
• When the upstream rejects a thinking signature, including with a 400 whose message says the block is bound to a different conversation, Claude Code removes earlier thinking blocks from the request, retries, and keeps them out of every later request. New responses still include thinking
• When the gateway or its upstream rejects the advisor tool entry in tools as an unrecognized tool type, Claude Code retries once without that entry and its anthropic-beta value. Later requests omit them. Claude Code recognizes this rejection by a 400 or 422 response whose message names the tool type after Input tag, such as Input tag 'advisor_20260301'. Before v2.1.280, Claude Code didn’t retry this rejection
• When the upstream rejects output_config.effort or its anthropic-beta value, the gateway sees the request once more without them. Later requests omit them. Your gateway needs no change if it forwards the upstream’s 400 unmodified and the message:
  • Names output_config.effort alongside Extra inputs are not permitted
  • Says the model doesn’t support the effort parameter
  • Starts with Unexpected value(s) and lists effort-2025-11-24 for the anthropic-beta header. Requires v2.1.310 or later. Developers whose ANTHROPIC_BETAS lists the value keep sending it and getting the 400, so have them remove that entry
• When the upstream rejects the context_management field or its anthropic-beta value, the gateway sees the request once more without them. Later requests omit them. Claude Code recognizes this rejection by its message, for example one containing context_management: Extra inputs are not permitted. Before v2.1.304, Claude Code didn’t retry this rejection
• When a 400 rejects another anthropic-beta value by name, the gateway sees the request once more without it if the retry covers that value
• When the upstream rejects a beta tool field other than defer_loading, such as strict, the 400 reaches the developer. Before it does, the gateway can see the request again without the tool search fields. To stop sending such fields, have developers set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

​

Retry without a rejected beta value

• The API’s sentence: the Unexpected value(s) sentence that lists the value for the anthropic-beta header
• A beta_header: token: capability_rejected: beta_header: followed by the value, a capability_rejected: token

• A value with its own retry, such as advisor or tool search: the gateway sees that capability’s own retry instead
• A value Claude Code doesn’t recognize: a value that a developer set through ANTHROPIC_BETAS stays on each request, so the developer’s requests keep failing with the 400. Have the developer remove the entry
• A bare invalid beta flag: Claude Code guesses which value the upstream rejected. If the request carried a value it guesses at, the gateway sees the request again without that value. If the 400 still reaches the developer, have your gateway name the rejected value in one of those forms

​

How long a rejected beta value stays out

​

Retry without tool search

​

Disable pre-release capabilities

• Context management and its context_management body field
• The beta tool schema fields, such as strict and defer_loading. The standard name, description, input_schema, and cache_control tool fields stay
• The structured-output output_config.format field. Requires Claude Code v2.1.287 or later
• The output_config.task_budget field
• MCP tool search, so every MCP tool loads upfront unless your organization keeps it on through managed settings

• The anthropic-beta values for extended context, interleaved thinking, and effort, which cloud providers also accept
• The top-level output_config.effort field. Automatic retry and error forwarding covers an upstream that rejects it
• The adaptive reasoning thinking field, which has no beta header
• The role: "system" entries that carry mid-conversation system messages
• The OAuth anthropic-beta value that subscription authentication requires
• Header values and body fields developers add themselves through ANTHROPIC_BETAS or CLAUDE_CODE_EXTRA_BODY

• On a direct connection without the HIPAA configuration, or through a gateway set with ANTHROPIC_BASE_URL, Claude Code keeps sending the tool-search beta header, defer_loading tool fields, and tool_reference blocks
• On a cloud provider, or signed in through a Claude apps gateway, the override has no effect
• In a session that gets the HIPAA configuration, the override has no effect and tool search stays off

​

Model discovery

​

When discovery runs

• Any CLAUDE_CODE_USE_* provider variable is set, even if ANTHROPIC_BASE_URL is also set
• ANTHROPIC_BASE_URL is unset or points at api.anthropic.com

​

Request and response

• Authorization: ANTHROPIC_AUTH_TOKEN as a bearer token, otherwise the apiKeyHelper value as a bearer token.
• x-api-key: the API key Claude Code resolved, such as ANTHROPIC_API_KEY. When a helper value is the only credential, this header carries it too, so the value arrives in both headers.

{
  "data": [
    {
      "id": "claude-sonnet-4-6",
      "display_name": "Claude Sonnet 4.6",
      "description": "Default model for everyday coding tasks"
    },
    { "id": "claude-opus-4-8" }
  ]
}

​

Picker entries and caching

• Same ID: the discovered ID exactly matches an existing row’s ID, or the two IDs are spellings of the same Fable version.
• Same model as a built-in alias: when a discovered explicit ID names the model that a built-in alias currently resolves to, the picker shows only the alias row. For example, while sonnet resolves to claude-sonnet-5-5, a discovered claude-sonnet-5-5 collapses into the sonnet row, and a discovered claude-sonnet-5 still gets its own row.

​

Related resources

• Gateway overview: what a gateway is and how to choose between Claude apps gateway and another product
• Other LLM gateways: how to roll out a gateway your organization runs and how it interacts with claude.ai subscriptions
• Roll out an LLM gateway for your organization: the admin checklist that uses this guide
• Connect Claude Code to an LLM gateway: per-developer configuration and the troubleshooting table
• Beta headers reference: the current set of anthropic-beta values
• Messages API: the API format an Anthropic-format gateway implements