Claude Code gateway contract: 10 traps that stall agents

Guide Claude Code gateway contract claude-opus-5-5claude-sonnet-5-5 Lazu

By Molly · Lazu Team

Short answer: pointing Claude Code's ANTHROPIC_BASE_URL at a gateway requires more than implementing the documented fields of the Anthropic Messages API. Between Claude Code 2.1.257 and 2.1.317, the CLI added a layer of client-side recovery and state tracking — when to auto-compact, when to strip a rejected parameter and retry, when to stop retrying, and how to track /effort support per model. Most of those branches inspect exact HTTP status codes, headers, and substrings inside error messages.

In early November 2026 we audited Lazu's relay pipeline line by line against Claude Code's source behavior. We found ten places where gateway behavior that looked reasonable on paper caused Claude Code to stall in retry loops, skip auto-compaction, or silently lose thinking blocks and prompt caches across turns. The fixes shipped in v0.7.273 (#179, #180, #181) and #208.

Here are all ten traps and how we fixed them. If you self-host Lazu, maintain your own LLM gateway, or debug strange Claude Code sessions behind a custom endpoint, you can use this list as a checklist.

The 10 traps at a glance #

# Scenario Common gateway behavior What Claude Code actually does What the gateway should do
1 Empty wallet or exhausted key budget Return 429 insufficient_quota on every protocol Treats 429 as a rate limit, retries 10 times, stalls ~3 minutes Return 402 billing_error on /v1/messages with x-should-retry: false
2 Prompt exceeds context window Replace upstream text with generic catalog copy Misses the overflow signal, skips /compact, aborts the turn Render prompt is too long: N tokens > M maximum
3 Upstream rejects context_management or an anthropic-beta flag Rewrite as a generic 400 bad_request Cannot tell which field or beta failed; self-healing retry never fires Preserve <field>: Extra inputs are not permitted and the rejected beta name
4 Upstream fails or times out after SSE : PING keep-alive Write raw JSON into the open HTTP 200 stream Sees truncated SSE without an error event Emit a well-formed event: error SSE frame once headers are committed
5 Round-robin routing across channels or key pools Route each turn independently Bound thinking signatures 400 or drop silently; prompt cache misses every turn Pin (user, session_id, model) to the channel and key that served the last turn
6 Re-serializing native SSE frames through a fixed DTO Drop unmodeled response fields Silently strips diagnostics, stop_details, and new usage counters Forward raw upstream SSE frames on native /v1/messages, patching only what is missing
7 Normalizing thinking through a 3-field struct Drop unknown nested keys on marshal Loses block_binding, between_tools, and newer thinking controls Preserve unmodeled keys inside thinking across normalization
8 Returning the upstream's internal model string Echo dated, prefixed, or dotted IDs Miscomputes compaction thresholds or disables /effort Rewrite model and message_start.message.model to the model name the client asked for
9 Top-level output_format on background calls; screenshots in tool history Reject output_format as unknown; fail every later turn on text-only bridges Session title/hook calls 400; one Read screenshot poisons the whole session Decode output_format alongside output_config.format; omit tool-result images with X-Lazu-Warning
10 Dropping speed: "fast" silently; tool calls to reasoning-only GPT-6 Strip speed with no notice; inject reasoning_effort: "none" on Chat Runs at standard speed unannounced; gpt-6.1-sol rejects "none" with 400 Emit X-Lazu-Warning: field_dropped:speed; replan reasoning-only GPT-6 tools onto /v1/responses

1. Returning 429 on an empty wallet stalls Claude Code for 181 seconds #

Gateways built around OpenAI's conventions often return HTTP 429 (insufficient_quota) for empty balances and exhausted key budgets on every wire. Codex treats 429 + insufficient_quota as terminal, but Claude Code treats any 429 without an explicit no-retry signal as a transient rate limit and backs off exponentially.

Measured on Claude Code 2.1.317 against a zero-balance key, a single prompt triggered 11 requests over 181 seconds before Claude Code finally printed the billing error.

The fix (#180):

  1. Split the status code by wire protocol: budget and wallet errors return HTTP 402 (billing_error) on /v1/messages — matching Anthropic's own API — while keeping 429 (insufficient_quota) on OpenAI and Gemini endpoints.
  2. Attach x-should-retry: false on every outlet that can emit a non-recoverable billing or quota error (pre-relay checks, the relay handler, and pre-stream error responses):
HTTP/1.1 402 Payment Required
x-should-retry: false
Content-Type: application/json

With both in place, the same zero-balance request drops from 11 requests / 181 seconds to 1 request / 0.4 seconds.

2. Rewriting "prompt is too long" breaks auto-compaction #

Starting in 2.1.285, Claude Code assumes a 1M-token context window behind custom gateways and relies on automatic compaction when a channel enforces a smaller window (such as 200K). To decide whether to compact, Claude Code matches Anthropic's exact wording:

prompt is too long: 214530 tokens > 200000 maximum

Lazu previously defeated that check in two places:

  • Pre-flight context validation rejected oversized requests with 400 protocol_bridge_unsupported ("estimated input tokens N exceed channel context limit M").
  • When an upstream returned "prompt is too long" (or "Input is too long" on Bedrock-backed channels), our error catalog replaced the message with cleaner house copy: "The input exceeds this model's context window...".

Both rejections were accurate, and both broke auto-compaction.

The fix (#181): Every context_length_exceeded path — pre-flight token checks, upstream 400s, and in-stream errors — now extracts the token count and limit and renders prompt is too long: N tokens > M maximum. Upstream internals stay sanitized, and Claude Code compacts on cue.

3. Generic 400 copy breaks strip-and-retry on context_management and anthropic-beta #

Between 2.1.275 and 2.1.314, Claude Code began sending context_management and newer anthropic-beta flags (effort-2025-11-24, compact-2026-09-04, inline-tools-2026-09-15) by default. Because custom gateways sit in front of varied backends, Claude Code includes a clean fallback: when a 400 names the rejected input field or beta token, the client strips that specific field or beta for the rest of the session and immediately retries.

When a gateway replaces upstream validation errors with generic copy like "The request body is malformed" or "Upstream rejected a beta feature", Claude Code never learns which parameter offended the upstream, so the retry never triggers.

The fix (#181): Extract the offending field path or beta token and re-render the exact shapes Claude Code parses:

  • Extra field: <field>: Extra inputs are not permitted
  • Rejected beta: Unexpected value(s) '<name>' for the 'anthropic-beta' header

4. Errors after an SSE : PING written as bare JSON #

Uncached prefill on hundred-thousand-token prompts routinely takes more than 15 seconds. To keep proxies and NAT tables from dropping idle connections, Lazu sends an SSE comment (: PING) every 15 seconds while waiting for the upstream.

The subtle bug is timing: the first : PING flushes HTTP 200 OK with Content-Type: text/event-stream. If the upstream then returns a 400 at second 25 or hits the 90-second first-event timeout, calling a standard JSON error responder writes raw, unprefixed JSON into the middle of an SSE stream. Claude Code sees : PING lines followed by invalid SSE framing and drops the stream without a readable error.

The fix (#181): Once response headers are committed on /v1/messages, any failure is emitted as a proper Anthropic SSE error event before closing the stream:

event: error
data: {"type":"error","error":{"type":"api_error","message":"..."}}

5. Stateless round-robin routing breaks bound thinking blocks and prompt caches #

Routing each request independently works for single-turn chat, but breaks multi-turn coding agents. On Claude 5.x models, cryptographic thinking signatures, prompt caches, and server-side state are bound to the upstream account that produced them:

  • If turn 1 lands on channel A and turn 2 lands on channel B (or rotates to a second API key in the same channel pool), models like claude-haiku-5-5 can reject the mismatched thinking block with a 400.
  • On claude-sonnet-5-5, cross-account turns can silently drop prior thinking blocks instead of failing loudly.
  • Every hop to a different account misses the prompt cache and pays full price to re-prefill the system prompt and repository context.

The fix (#179): Session-to-channel and key affinity (session_affinity). Lazu reads X-Claude-Code-Session-Id (along with session headers from Codex, OpenCode, and Goose) and stores the winning (channel_id, key_index) in Redis under (user, session_id, resolved_model) with a sliding 1-hour TTL. Subsequent turns reuse the exact channel and upstream key unless the channel is disabled, in circuit-breaker retreat, or unable to plan the new turn's protocol features losslessly.

6. Re-serializing native SSE frames strips diagnostics, stop_details, and new usage keys #

Gateways often unmarshal every streaming SSE frame into a typed struct (such as dto.ClaudeResponse) to read token counts, then re-marshal the struct back out. Whenever Anthropic adds fields to streaming events — diagnostics, stop_details, response-side context_management, or new usage breakdowns — a fixed DTO silently strips every field it hasn't modeled yet.

The fix (#181): On native /v1/messages streams, Lazu now forwards the upstream's raw SSE frame bytes intact, patching only message_start.message.model when needed and filling usage counters only if the upstream omitted them.

7. Losing nested thinking keys during request normalization #

The mirror image happens on inbound requests. Unmarshaling thinking into {type, budget_tokens, display} and marshaling it back drops newer subkeys such as block_binding and can mishandle thinking.type: "between_tools".

The fix (#181): Preserve unknown keys inside thinking across normalization, mutating only the specific budget or compatibility fields the channel policy governs.

8. Echoing the upstream's internal model ID confuses compaction and /effort #

Upstreams routinely answer with dated model IDs (claude-sonnet-5-5-20260929), vendor-prefixed names (anthropic/...), or base names after the gateway stripped a -thinking suffix. Between 2.1.301 and 2.1.314, Claude Code inspects the response model field to look up context limits and /effort capabilities. A mismatched, prefixed, or dotted response model ID can trigger repeated compaction loops or lock /effort controls out.

The fix (#181): Regardless of whether a channel defines an explicit model_mapping, /v1/messages responses always write the exact model name the client requested on non-streaming responses and on message_start.message.model (leaving subsequent stream frames untouched).

9. Top-level output_format and screenshots inside tool_result history #

When users point Claude Code at Lazu to run non-Anthropic models over protocol translation, two edge cases showed up immediately:

  1. Background structured outputs: Session title generation, memory recall, and prompt hooks can send top-level output_format instead of output_config.format. Because Lazu's protocol planner refuses unknown fields rather than dropping them silently, leaving output_format unmodeled caused background title requests to 400.
  2. Screenshots in tool_result blocks: If an agent reads a screenshot via a tool on turn 3 and switches to a text-only coding model on turn 10, that single historical image in tool_result causes every subsequent turn to fail.

The fix (#181): The Anthropic Messages decoder now accepts top-level output_format as an alias for output_config.format and treats request diagnostics as advisory. When bridging an Anthropic client to a model whose catalog entry lacks image input, Lazu replaces images inside tool_result blocks with an explicit text note and emits X-Lazu-Warning: omitted:tool_result_image (direct user-submitted images still fail closed if the target model cannot view them).

10. Silent field drops and tool calls on reasoning-only GPT-6 models #

Two final rules keep gateway rewrites honest:

  • Name every dropped field: When a channel does not allow fast mode (speed: "fast"), silently deleting speed leaves the user thinking they are benchmarking fast mode while getting standard latency. Lazu now records every channel-stripped parameter in X-Lazu-Warning: field_dropped:<name> (#181).
  • Route reasoning-only GPT-6 tool calls to /v1/responses: OpenAI's gpt-6 family rejects function tools on /v1/chat/completions while reasoning is active. Variants like gpt-6-luna and gpt-6-sol accept reasoning_effort: "none" as an escape hatch, whereas reasoning-only variants (gpt-6.1-sol, gpt-6.2-sol, gpt-6-astra) start at "low" and reject "none" with an HTTP 400. Lazu now checks the synced catalog's reasoning toggle (CanDisableReasoning): stop-capable variants only receive "none" when needed on Chat, and Anthropic Messages tool calls targeting reasoning-only GPT-6 variants automatically replan onto /v1/responses, where reasoning and function tools work together (#208).

Summary: treat client control flow as part of the wire contract #

All ten bugs point to the same three engineering rules:

  1. Control-flow signals (402, x-should-retry, overflow and validation wording, event: error, message.model) are part of the API contract, not cosmetic strings the gateway is free to rephrase.
  2. Keep native paths byte-transparent, fail closed before lossy cross-protocol bridges, and emit X-Lazu-Warning whenever a registered degradation runs — documented in docs/protocol-conversion-architecture.md.
  3. Coding-agent traffic is stateful across turns, so routing has to respect the upstream account boundary where thinking signatures and prompt caches live.

All of the code and regression tests above are open source in lazu-ai/lazu. If you want a hosted endpoint with this contract already running, one key connects Claude Code to claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5, or bridged GPT and DeepSeek models:

export ANTHROPIC_BASE_URL=https://api.lazu.ai
export ANTHROPIC_AUTH_TOKEN=sk-lazu-...
claude
Related
2026-11-18OpenCode custom provider: Claude, GPT and DeepSeek on Lazu 2026-09-30Claude Code custom API: Opus, Sonnet and Haiku 5.5 on Lazu 2026-09-30LLM API pricing comparison: Claude, GPT, Gemini, DeepSeek

Try it with a key

Start free