A translating gateway can return a readable reply to Claude Code and still drop the tool result the next request depends on.

When that happens, the client can keep running while the model request fails halfway through a task. This article is for anyone who routes a coding agent through a translating gateway and wants to know what to check before trusting the route. By the end you will know what the translator has to preserve across a tool round trip, how the Messages, Chat Completions and Responses request shapes map onto each other, and how one route behaved when we tested it ourselves. The results come from our own run of Claude Code 2.1.319 against a LiteLLM 1.93.0 gateway, and the mapping comes from the vendor references we link. We pointed Claude Code at a gateway backed by GPT to see whether a tool result makes it back into the conversation. In our setup, the route returned text and completed the exchange after we sent back a tool result.

The article covers four points in order, then reports what the route did in our run.

  1. What the translator must preserve across one tool round trip.
  2. How the fields of the Messages, Chat Completions and Responses APIs map onto each other.
  3. Why a passthrough or reverse-translation route needs its own test.
  4. Which credential each request runs under.

Translating between two API contracts

The route joins two API contracts, so we start with which component speaks which one.

Claude Code is the client and the harness that runs tools. In LiteLLM's tutorial, the client sends Anthropic Messages requests to LiteLLM, which translates each request into a target provider's format and forwards it, then translates the reply back into Messages format. We ran Claude Code 2.1.319 against a LiteLLM 1.93.0 gateway that listened only on the loopback interface, so only this machine could reach it. The gateway's configuration routes the requested model name to an Azure OpenAI deployment of gpt-6-luna, model version 2026-09-22, through the Responses API. The client-facing endpoint was /v1/messages, as in the tutorial, and the Messages reference we worked from is API version 2026-10-21.

Anthropic does not support routing Claude Code to non-Claude models through any gateway, and it does not endorse, maintain, or audit third-party gateway products. We check that support position and Anthropic's credential guidance before choosing a route.

Three places: a client environment with Claude Code, a translation process with LiteLLM and its route configuration, whose note reads Upstream API: Responses, and an inference provider with the GPT endpoint. Four lanes join them in order: request in Messages format, request in Responses format, reply in Responses format, reply in Messages format. At the end one pale upright card with a green band rests at Claude Code.
The translator sits between two API contracts. In the figure, note where each of the three components runs and which contract each hop uses.
Figure text

Claude Code sends a Messages request through a translator to a configured GPT endpoint, and the response returns through the translator. Claude Code runs in the client environment, LiteLLM runs in its own process, and the GPT endpoint runs at the provider.

  • Three places, two formats
  • Messages format (upright card)
  • Responses format (sideways card)
  • The upstream format is chosen in LiteLLM's configuration. Changing the address leaves the gap between the two formats unchanged, and a readable reply does not show how the conversion handled the details.
  • 1 Request, Messages format
  • 2 Request, Responses format
  • 3 Reply, Responses format
  • 4 Reply, Messages format
  • Claude Code: Client, and the harness that runs tools
  • LiteLLM: Converts both directions
  • Route configuration: Picks the upstream format
  • GPT endpoint
  • Inference provider
  • Upstream API: Responses
  • LiteLLM converts the reply back into Messages format for Claude Code.

Sources: [1] Use Claude Code with Non-Anthropic Models | liteLLM; [2] Other LLM gateways - Claude Code Docs.

What protocol translation can lose

The translator sits between every request and reply, so we start with what it can lose.

Protocol translation can alter or drop any of these:

A readable reply tells us little about how the translator handled those details. A coding task also needs the return path to preserve the tool-call identifier and the next request to preserve the tool result, so we test each separately.

The tool result needs another upstream exchange

The first point is a single tool call, which shows what the translator must preserve for a coding task.

Take a synthetic task with a harmless tool named read_sample that returns the fixed string sample-value without reading or writing a file. Assume the harness exposes and permits that tool. After the tool returns, the model still needs to receive the value, and on this route that takes a second trip upstream.

This route's tool flow follows LiteLLM's translation design.

  1. Claude Code sends a Messages request containing the task and tool definition to LiteLLM.
  2. LiteLLM converts that request to the API chosen by the route configuration and sends it to the GPT endpoint.
  3. The upstream response requests read_sample using that API's format.
  4. LiteLLM converts that response into a tool request Claude Code can interpret.
  5. The harness invokes the permitted tool in its execution environment and collects sample-value.
  6. Claude Code sends a continuation Messages request containing the tool result back to LiteLLM.
  7. LiteLLM converts and forwards the continuation for a second upstream exchange.
  8. LiteLLM converts the final upstream response and passes it back to Claude Code.

The continuation request in steps 6 and 7 is the model's only source for the value, so across the two exchanges the translator must keep the tool result linked to its call and convert the responses correctly. In our run, we saw the tool request, submitted tool result, and final answer.

Three stations: Claude Code, LiteLLM and the GPT endpoint, with a floor mark numbered 5 beside Claude Code labelled Tool runs here. Lanes 1 and 2 carry the first request up, lanes 6 and 7 carry the second request with the tool result up, and lanes 3 and 4 bring each reply back. Lanes on the Claude Code side are green for Messages format, lanes on the GPT endpoint side blue for the upstream format. At the end a pale upright card tagged Final response rests at Claude Code.
  1. Messages request (step 1): Claude Code sends a Messages request containing the task and tool definition to LiteLLM.
  2. First upstream exchange (steps 2 and 3): LiteLLM converts that request to the API chosen by the route configuration and sends it to the GPT endpoint, and the upstream response requests read_sample.
  3. Tool request (steps 4 and 5): LiteLLM converts that response into a tool request Claude Code can interpret, and the harness invokes the permitted tool and collects sample-value.
  4. Continuation (step 6): Claude Code sends a continuation Messages request containing the tool result back to LiteLLM.
  5. Second upstream exchange (step 7): LiteLLM converts and forwards the continuation for a second upstream exchange.
  6. Final response (step 8): LiteLLM converts the final upstream response and passes it back to Claude Code.
The steps follow the translation design LiteLLM documents, for a synthetic task. In our run we saw the tool request, the submitted tool result and the final answer.
A platform holds Claude Code and its tool; LiteLLM and the GPT endpoint stand outside it. Seven lanes in order: the tool request comes in, run the tool, result collected, second request with the result, second request converted, final reply, final answer converted. The two tool lanes stay between Claude Code and the tool; the others pass LiteLLM. At the end a pale card tagged Final answer rests at Claude Code.
The client sends the tool result in a continuation through the gateway for a second upstream exchange. Running the tool and collecting its result happen inside the harness, on the two lanes between Claude Code and its tool; every other lane crosses the gateway. The figure starts where the tool request reaches Claude Code, which is step 4 of the eight-step list under this section's heading, and numbers its own lanes from there.
Figure text

In LiteLLM’s documented design, the gateway translates a first Messages request for a GPT API and returns the translated tool request to the Claude Code harness. The harness executes the tool, collects its result, and sends a second request through LiteLLM before receiving the translated final answer. The figure shows the tool request, the tool run, the second request and the final answer, numbered 1 to 7; the first request and its reply are already made.

  • The result stays tied to the call
  • Messages format (upright card)
  • Upstream format (sideways card)
  • Tool result, tied to call (tag)
  • Running the tool and collecting its result happen inside the harness; every other step crosses the gateway. Test that the tag and the result both survive the crossing.
  • 1 Tool request comes in
  • 2 Run the tool
  • 3 Result collected
  • 4 Second request, with the result
  • 5 Second request, converted
  • 6 Final reply
  • 7 Final answer, converted
  • Claude Code: Client, and the harness that runs tools
  • Tool
  • LiteLLM: Converts on every crossing
  • GPT endpoint: Configured GPT API
  • Final answer
  • The final answer comes back through LiteLLM to Claude Code.

Sources: [1] Use Claude Code with Non-Anthropic Models | liteLLM; [2] Other LLM gateways - Claude Code Docs.

Compare the request shapes to work out the mapping

The second point is the field mapping that the LiteLLM conversion steps in that flow depend on.

The Messages, Chat Completions, and Responses references each define their own objects for related operations. For our route, the translator must map these fields to Responses, the configured upstream API.

We compare how the three APIs represent each kind of information and what the translator must preserve for our route.

Sources: Messages - Claude API Reference, Responses | OpenAI API Reference, Chat | OpenAI API Reference, Use Claude Code with Non-Anthropic Models | liteLLM, Anthropic | liteLLM.

InformationAPI fieldsWhat the translator has to get right
System or instruction contentMessages uses separate system content; Chat Completions uses system or developer messages; Responses has instructionsInstruction handling on continuation
Conversation contentMessages and Chat Completions use role-tagged messages; Responses accepts input as text or an array of input itemsConversation conversion
Tool definitionMessages tools have name and input_schema; Chat function tools put name and parameters under tools[].function; Responses function tools use type: "function", name, and parametersMapping for the selected schema and model
Model's tool callMessages returns a tool_use block with id and input; Chat returns tool_calls with id and function.arguments; Responses uses function_call with call_id and argumentsArgument and identifier conversion
Caller-submitted tool resultMessages accepts tool_result with tool_use_id; Chat accepts a role: "tool" message with tool_call_id; Responses accepts function_call_output with call_idResult conversion and keeping the link to the original call
Stream eventsMessages has content_block_delta with index; Chat chunks contain choices[].delta; Responses has named events such as response.output_text.delta with output_indexEvent association, ordering, and termination
UsageMessages exposes usage in message_delta; Chat reports prompt_tokens and completion_tokens in usage; Responses reports input_tokens and output_tokens in usageToken-class and final-usage conversion
ErrorsResponses error object includes code and message (partial schema)Upstream-to-client error conversion, including HTTP status and body

Routes that continue a Responses conversation with previous_response_id do not carry prior instructions forward (instructions reference), so we send the instructions again on that continuation.

We traced one Messages request through LiteLLM to gpt-6-luna and back, field by field, in one request traced through LiteLLM.

The two tool rows of the table can be checked against that trace. This Python script holds the tool definition and the tool call from it, each as it appeared on the client side and on the upstream side of LiteLLM, and prints which field on one side holds the same value on the other. It compares the captured objects by value and holds none of LiteLLM's translation code.

"""Match fields by value between the two shapes of one tool and one tool call.

The four objects come from one request we captured on each side of LiteLLM.
The script compares those captures. It holds none of LiteLLM's translation code.
"""
import json

MESSAGES_TOOL = {
    "name": "get_weather",
    "description": "Get the current weather for a city.",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string", "description": "City name"}},
        "required": ["city"],
    },
}
RESPONSES_TOOL = {
    "type": "function",
    "name": "get_weather",
    "strict": False,
    "description": "Get the current weather for a city.",
    "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string", "description": "City name"}},
        "required": ["city"],
    },
}
RESPONSES_CALL = {
    "id": "fc_...", "type": "function_call", "status": "completed",
    "arguments": '{"city":"Paris"}', "call_id": "call_...", "name": "get_weather",
}
MESSAGES_CALL = {
    "type": "tool_use", "id": "call_...", "name": "get_weather",
    "input": {"city": "Paris"},
}


def decoded(value):
    """Parse a string that holds a JSON object, so it compares equal to the object."""
    if isinstance(value, str) and value.startswith("{"):
        return json.loads(value)
    return value


def field_map(title, left, right):
    """Print, for each field on the left, the fields on the right with its value."""
    print(title)
    matched = set()
    for key, value in left.items():
        twins = [name for name in right if decoded(right[name]) == decoded(value)]
        matched.update(twins)
        notes = [t if right[t] == value else t + " (JSON string parsed)" for t in twins]
        print(f"  {key:<13}", "-> " + ", ".join(notes) if notes else "no match")
    print("  right only:  ", ", ".join(k for k in right if k not in matched) or "none")


field_map("tool definition, Messages request to Responses request",
          MESSAGES_TOOL, RESPONSES_TOOL)
field_map("tool call, Responses reply to Messages reply", RESPONSES_CALL, MESSAGES_CALL)

It prints:

$ python3 field_map.py
tool definition, Messages request to Responses request
  name          -> name
  description   -> description
  input_schema  -> parameters
  right only:   type, strict
tool call, Responses reply to Messages reply
  id            no match
  type          no match
  status        no match
  arguments     -> input (JSON string parsed)
  call_id       -> id
  name          -> name
  right only:   type

In this capture the schema moved from input_schema to parameters unchanged, and the Responses tool gained type and strict. On the way back, call_id became the id of the tool_use block and the arguments string became the input object. The upstream item's own id and its status have no counterpart in the Messages block, and type is on both sides with different values, function_call and tool_use.

The four objects come from one request sent with curl through LiteLLM 1.106.4, a later version than the 1.93.0 gateway in the Claude Code run this article reports, so the output is that version's mapping for one tool. The ids are shortened to their prefix, so the script matches call_... on the prefix alone; in the full capture the two ids were the same string. To check another route, replace the four objects at the top with the same four from your own capture.

Passthrough and reverse translation need separate tests

The third point keeps results from other routes out of the verdict.

An Anthropic passthrough route forwards an Anthropic-shaped request toward Anthropic, while a Messages-to-GPT route uses a different API contract upstream. So even when a passthrough route works, we test Messages-to-GPT translation separately.

The LiteLLM Anthropic-provider examples describe the reverse mapping from OpenAI-format input toward Anthropic. They show how to convert OpenAI's response_format for supported structured-output cases and handle reasoning_effort with model-specific mappings to Anthropic thinking controls. thinking passes through unchanged only on the documented native Messages passthrough path.

Claude Code's gateway maintenance guidance warns that newly added capabilities can break when a gateway does not forward them. If we pin the client and leave the translation layer unpinned, part of the behavior still depends on the gateway version we run.

Which credential each request runs under

The fourth point is the credential: the route also changes which credential each request runs under, and that affects limits and billing.

A client-facing credential, if one is configured, authenticates Claude Code to the gateway. The gateway's upstream credential authenticates its request to the provider, and the two can belong to different account systems and different billing arrangements. Claude Code's gateway rollout keeps the provider credential at the gateway and issues gateway credentials to developers.

When a gateway credential variable or apiKeyHelper is active, that credential replaces Claude Code's saved subscription login for those requests. Setting only ANTHROPIC_BASE_URL leaves the subscription credential in place and can keep a saved subscription login active with its limits and billing. We check the active credential separately from the base URL (subscriptions and gateways).

In our setup the gateway held the provider credential and had no client authentication configured. A gateway that holds provider credentials is worth attacking for that reason alone, and The gateway as an attack surface covers how to separate its keys and keep it off the internet.

What we saw when we tested the route

We ran the route and recorded what came back.

The streamed Messages reply sent these events in this order:

  1. message_start
  2. content_block_start
  3. content_block_delta
  4. content_block_stop
  5. message_delta
  6. message_stop

It ended with stop_reason: end_turn and reported usage. In a raw Messages tool round trip, the first reply had stop_reason: tool_use, a continuation submitted tool_result, and the final reply contained the fixed value.

Claude Code then completed an end-to-end task with the Read tool in three turns and two Read calls. Its first Read used a wrong path outside the working directory and got an error, after which the model retried and returned the token we had planted in the test file. The client reported usage and an estimated cost.

A deliberately invalid client credential got HTTP 200 with usage, and the upstream call ran.

A request carrying top_k, which the GPT upstream does not support, returned HTTP 200 with a normal reply and no warning in the response body. The response does not show whether the gateway dropped top_k or forwarded it. The gateway's configuration enables parameter dropping and lists these parameters for removal on this route:

Each route entry can have its own drop list.

Results by feature

The table lines each feature up against what Claude Code needs from it and what we saw.

Each feature's Claude Code requirement and what our route returned.

Sources: Messages - Claude API Reference, Responses | OpenAI API Reference, Chat | OpenAI API Reference, Use Claude Code with Non-Anthropic Models | liteLLM, Anthropic | liteLLM, Other LLM gateways - Claude Code Docs.

FeatureWhat Claude Code needsWhat happened
Tool schema and IDsDecode the requested operation and associate its resultTool request and continuation completed through the route
Tool resultsSubmit the result in a continuationFinal reply contained the fixed value
StreamingCoherent Messages-facing eventsThe reply sent six event types in order and ended with end_turn
UsageUsage fieldsMessages and Claude Code both reported usage; neither states how its cost estimate is calculated
ErrorsA failure the client can detectThe invalid-token and top_k requests both returned 200
AuthenticationGateway checks the client credentialThe gateway accepted the deliberately invalid client token and held the provider credential

What to take from this

In our run, the invalid-token and top_k requests both returned HTTP 200.

What an attacker targets here

The route we tested accepted a deliberately invalid client token, so anyone who reaches this gateway can spend the provider credential it holds.