<!-- Lazu · Claude Code gateway contract: 10 traps that stall agents · https://lazu.ai/blog/claude-code-gateway-contract -->

# Claude Code gateway contract: 10 traps that stall agents

2026-11-18 · Lazu team

*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](https://github.com/lazu-ai/lazu/pull/179), [#180](https://github.com/lazu-ai/lazu/pull/180), [#181](https://github.com/lazu-ai/lazu/pull/181)) and [#208](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/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
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:

```text
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](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/181)):** Once response headers are committed on `/v1/messages`, any failure is emitted as a proper Anthropic SSE error event before closing the stream:

```text
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](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/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](https://github.com/lazu-ai/lazu/pull/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`](https://github.com/lazu-ai/lazu/blob/main/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`](https://github.com/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:

```bash
export ANTHROPIC_BASE_URL=https://api.lazu.ai
export ANTHROPIC_AUTH_TOKEN=sk-lazu-...
claude
```
