Messages API
Use POST /v1/messages to call a chat model with the Anthropic Messages request and response shapes. The endpoint works with direct Anthropic models and with models served through the OpenAI Responses protocol. The model you choose decides the backend protocol; the endpoint you call decides the shape of the request and response.
This version supports text conversations with images and PDF documents, client tools, tools the gateway runs, preset agents, as one response or as a stream, and the settings listed below. The capability matrix lists what each kind of target accepts. Other optional settings are not available yet. A request that uses one of them is rejected before it reaches the model.
Before you begin
You need:
- the API URL shown in the platform portal
- an API key with
invokeaccess to a chat model - the model ID from
GET /v1/models
Authenticate with your platform API key as a bearer token: Authorization: Bearer <key>. The x-api-key header is not supported. For an Anthropic model, the gateway sends the connector's Anthropic key; your platform key never reaches Anthropic. The gateway always calls Anthropic with API version 2026-10-21. The anthropic-version header your client sends does not change it, and older API versions are not emulated.
curl -sS "$API_BASE_URL/v1/messages" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL_ID",
"max_tokens": 1024,
"system": "Answer in one sentence.",
"messages": [{"role": "user", "content": "What is the capital of France?"}]
}'
With the Anthropic Python SDK, set the base URL to the API URL without /v1 and pass the key as an auth token:
import anthropic
client = anthropic.Anthropic(base_url="https://api.<your-domain>", auth_token="cm_api_…")
message = client.messages.create(
model="YOUR_MODEL_ID",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
)
print(message.content[0].text)
Supported request
| Member | Support |
|---|---|
model | Required. A model, model alias or preset agent ID. A preset agent accepts fewer members; see Preset agents. |
max_tokens | Required integer. null is rejected. 0 is sent to the model as given. |
messages | Required and not empty. Roles user and assistant. A final assistant message (a prefill) returns 400 unless the model is an Anthropic model. |
system | A string, or a list of text blocks joined with a blank line. Blocks with cache_control keep their boundaries; see Prompt caching and user ID. |
metadata | Only user_id. See Prompt caching and user ID. |
temperature, top_p, top_k, stop_sequences, thinking, output_config | See Settings. |
tools, tool_choice | See Tools. |
stream | true or false. See Streaming. |
mcp_authorizations | A gateway extension carrying OAuth tokens for MCP tool servers. See MCP authorizations. |
Message content is a string or a list of blocks. User messages accept text, image, document and tool_result blocks. Assistant messages accept text, thinking, redacted_thinking, tool_use, and cm_gateway mcp_tool_use and mcp_tool_result blocks, so you can send back earlier answers, including their thinking, tool calls and gateway tool activity. For an Anthropic model they also accept web search and web fetch blocks and citations on text blocks.
A request that ends with an assistant message asks the model to continue that message. Models served through the Responses protocol cannot continue a message, so the gateway rejects the request instead of returning a new answer. For an Anthropic model the gateway sends the request as given, and the model decides; current Claude models reject a prefilled final assistant message.
Any other request member, including mcp_servers and service_tier, returns 400. So does any other block type, non-null citations on any block other than an assistant text block, and cache_control where Prompt caching and user ID does not list it. The error message names what is not supported.
Images and documents
| Block | Supported sources | Sent to a Responses model as | Sent to an Anthropic model as |
|---|---|---|---|
image | base64 with media_type image/jpeg, image/png, image/gif or image/webp; url | input_image with a data URL or the URL | a native image block |
document | base64 with media_type application/pdf; url | input_file with file_data as a data URL, or file_url | a native document block |
Images and documents are accepted in user messages only. file sources (provider file IDs), text and content document sources, and the document options title, context and citations return 400. The gateway forwards URLs without downloading them; whether the model accepts a given image or PDF is up to the model and its backend.
Settings
The gateway checks these values the same way for every model, before it calls the model. A null effort or format is the same as leaving it out. Otherwise, output_config.effort must be low, medium, high, xhigh or max, and output_config.format must be {"type": "json_schema"} with a schema that is present and not null. Any other value returns 400. The table shows how each accepted setting reaches the model.
| Setting | Anthropic model | Responses model |
|---|---|---|
temperature, top_p | 400 at any value, including defaults such as temperature: 1. | Sent as given. |
top_k | 400 at any value, including 0. | 400: the Responses protocol has no counterpart. |
stop_sequences | Sent as given. An empty list is the same as none. | A non-empty list returns 400. An empty list is accepted. |
thinking | {"type": "adaptive"}, with an optional display of summarized or omitted, {"type": "disabled"} and {"type": "between_tools"} are sent as given. The model decides which modes it supports. | Any explicit thinking returns 400. Adaptive thinking is not an effort level, so it is never translated. |
output_config.effort | Sent as given. | Sent as reasoning.effort. The model can still reject a value it does not support; only some models accept max. |
output_config.format | Sent as given. | Sent as a strict text.format JSON Schema named output, with the schema unchanged. |
A null temperature, top_p or top_k is the same as leaving it out. Anthropic API version 2026-10-21 has no sampling settings, so the gateway rejects them for an Anthropic model instead of dropping them. For a preset agent on an Anthropic model, a locked temperature or top-p fails every request until the agent's owner clears the lock.
{"type": "enabled", "budget_tokens": …} thinking returns 400: none of the supported Anthropic models accepts a thinking budget, and the gateway never converts a budget into an effort. A budget_tokens member on any other thinking type also returns 400, as do other thinking members besides type and display and other output_config members.
Tools
Declare your own tools in tools. Each tool is {"name", "description", "input_schema", "strict"}, with an optional "type": "custom"; name and an input_schema object are required. A name has 1 to 128 letters, digits, _ or -, and each name is unique. A Responses model accepts names up to 64 characters, so a longer name returns 400 for it. The gateway does not run these tools: the model's calls come back to you as tool_use blocks with stop_reason: "tool_use". Run the tool, then send the assistant content back unchanged followed by a user message with a tool_result block for each call.
| Request | Sent to a Responses model as | Sent to an Anthropic model as |
|---|---|---|
| A tool | A function tool whose parameters is the input_schema unchanged. strict is sent as given, and as false when omitted, since a Responses tool without strict is strict. | A native tool |
tool_choice auto, none | auto, none | Sent as given |
tool_choice any | required | Sent as given |
tool_choice {"type": "tool", "name": …} | A named function choice | Sent as given |
disable_parallel_tool_use | parallel_tool_calls with the opposite value. Omitted, it is not sent. | true is sent as given; false is the default |
Assistant tool_use | A function_call with the same ID, name and input as its arguments | A native tool_use block |
User tool_result | A function_call_output for the same call ID | A native tool_result block |
A forced choice, any or a named tool, is never weakened to auto: a model that cannot honor it returns 400. Most Responses models served by the platform and some Anthropic models do not accept a forced choice. A named tool must be one of the declared tools.
tool_result content is a string or a list of text and image blocks. Within a user message, results and other blocks keep their order. The Responses protocol has no error flag for a function result, so a result with "is_error": true reaches a Responses model as the JSON text {"is_error": true, "content": <the result content>} when its content is a string. Content that is a list of blocks keeps its blocks, so images stay images, after a leading text block {"is_error":true}. An Anthropic model receives is_error natively.
Provider-hosted tool types return 400, except web search and web fetch for an Anthropic model. Options on your own tools other than cache_control return 400. If a declared name is also a gateway tool that you may use, such as a registered MCP tool, the gateway runs it itself; see Gateway tools.
Web search and web fetch
For an Anthropic model, or a model alias that resolves to one, tools can declare Anthropic's web search tool {"type": "web_search_20250305", "name": "web_search"} and web fetch tool {"type": "web_fetch_20250910", "name": "web_fetch"}. Anthropic runs these tools; the gateway sends the declarations to the model and returns what the model did.
Any caller allowed to invoke the Anthropic model, including through an alias, can declare these tools. There is no separate gateway setting to turn them on. Anthropic bills web searches to the account behind the model's Anthropic connector, in addition to token costs.
- Both tools accept
max_uses,allowed_domainsorblocked_domains(not both),cache_control,strictandallowed_callers. Web search also acceptsuser_location; web fetch also acceptsmax_content_tokensandcitations.allowed_callersmay only be["direct"]. Any other member, name or tool version returns400. - A tool of your own with the same name as a declared web search or web fetch tool returns
400; on its own, a tool of yours namedweb_searchorweb_fetchis an ordinary client tool.tool_choicecan name them. - A Responses model or a preset agent returns
400for these tools and for their blocks inmessages.
The response holds a server_tool_use block for each call and a web_search_tool_result or web_fetch_tool_result block for its result, followed by the model's text, which can carry citations. You don't run these calls. To continue the conversation, send the assistant content back unchanged. A finished call and its result do not need the tool to still be declared, but a call that has no result yet does.
A search or a fetch can also fail. Its result block then holds {"type": "web_search_tool_result_error", "error_code": "…"}, or web_fetch_tool_result_error for a fetch, in place of the results; Anthropic chooses the code. The model continues with that error, and you send the block back unchanged, like any other result.
| Stop reason | What to do next |
|---|---|
pause_turn | Anthropic paused a long turn. Send the assistant content back as the last message, without a new user message and with the same tools. The next response continues the turn; if a call was left without a result, it starts with that result. The gateway never resumes a paused turn by itself. If a paused turn also calls a gateway tool, the request fails with 502 (or a stream error event), because nothing would run that call. |
tool_use | The model also called one of your tools, and a web search or fetch in that turn may not have run yet. Send your tool_result blocks as usual, with the same tools. The next response starts with the results of the calls that had not run. |
usage.server_tool_use holds web_search_requests and web_fetch_requests when the model reported both counts for every model request; otherwise it is left out. max_uses applies to each model request: when the gateway runs gateway tools, one Messages request makes several model requests, and each can use the tools up to max_uses times. Platform usage reports count tokens only, not searches or fetches.
Prompt caching and user ID
For an Anthropic model, cache_control marks a prompt cache breakpoint, as in the Anthropic API. It is accepted on system text blocks, user text, image and document blocks, assistant text, tool_use, server_tool_use, web_search_tool_result and web_fetch_tool_result blocks, tool_result blocks and the text and image blocks inside them, and tools. The value is {"type": "ephemeral"} with an optional ttl of 5m or 1h. A null cache_control or ttl is the same as leaving it out. Any other type, TTL or member returns 400, and so does cache_control on thinking, redacted_thinking, cm_gateway mcp_tool_use and mcp_tool_result blocks, and blocks inside mcp_tool_result. The gateway sends each breakpoint where you placed it. It does not check how many breakpoints you send or the order of their TTLs; the model rejects a request that breaks its rules.
When a system block has a breakpoint, the model receives your system blocks as you sent them, after any system text the platform adds, and the gateway's tool instructions follow in a separate block without a breakpoint. Without a breakpoint in system, your system prompt and the gateway's text are sent as one block.
metadata accepts only user_id, a string that is sent to an Anthropic model unchanged, including "". A null metadata or user_id, or an empty metadata object, is the same as leaving it out.
A Responses model returns 400 for any cache_control and for metadata.user_id. Preset agent requests reject both; see Preset agents. Cache reads and writes are reported in usage.
Gateway tools
To let the model use a registered MCP or RAG tool, declare it in tools by its gateway-qualified name, the name the gateway's MCP tools/list returns, with its input schema. The gateway runs each call to a declared gateway tool, after checking that you may use it, and continues the answer with the result. It never adds tools you did not declare. A call to a name you did not declare is not run: the model receives an error result instead.
The response shows each call the gateway handled and its result as MCP blocks of a virtual server named cm_gateway:
[
{"type": "mcp_tool_use", "id": "call_1", "name": "lookup", "server_name": "cm_gateway", "input": {"query": "Paris"}},
{"type": "mcp_tool_result", "tool_use_id": "call_1", "is_error": false, "content": [{"type": "text", "text": "…"}]},
{"type": "text", "text": "Paris is the capital of France."}
]
With the Anthropic Python SDK 2.3.0 or TypeScript SDK 1.3.0, use the beta client (client.beta.messages.create() or client.beta.messages.stream()) for gateway-tool responses. It types the MCP blocks, and sending its final content back replays them without running the tool again. The ordinary clients have not been checked with these blocks in these versions.
Blocks follow the model's turns: a turn's calls come first, then their results, then the next turn. Calls the model made in parallel are therefore followed by all their results, while sequential calls alternate with their results. When a turn also calls your own tools, their tool_use blocks keep their place among the turn's calls, the gateway still runs its own calls, and the response ends with stop_reason: "tool_use". Send your tool_result blocks in the next user message as usual.
A turn with a tool call the gateway cannot act on fails the request before any gateway tool of that turn runs. This happens when a gateway tool call is unfinished or has no ID or name, or when one of your tool calls is unfinished beside the turn's gateway calls. A request that does not stream returns 502 with api_error and the message the model failed to complete the response. A stream ends with an error event carrying the same error instead of message_stop. The stream may already hold blocks of that turn; do not run their tool calls. Send the request again.
By default the gateway makes at most 100 model calls per request, counting the first. A request that finishes, or hands tool calls back to you, on the 100th call succeeds as usual. If the gateway's tool results would need another model call beyond that limit, the request fails with api_error: a unary request returns 500, and a stream ends with an error event instead of message_stop. This limit is separate from max_tokens, which limits the output of each model call.
Send cm_gateway blocks back unchanged in later requests. The gateway turns them into ordinary tool calls and results for the model, keeping each turn and its thinking together; on the next model input, the gateway's results come before your own results and text. Replayed blocks are history only: they are never run again and do not need the tool to still be declared or available. An mcp_tool_use with another server_name, or an mcp_tool_result without an earlier cm_gateway call with its ID, returns 400.
Request-supplied MCP server URLs are not supported, and mcp_servers returns 400.
Preset agents
Send a preset agent ID as model to run the agent. The agent supplies the system prompt, tools and locked settings, so a preset agent request accepts only these members:
| Member | Value |
|---|---|
model | Required. The agent ID. |
max_tokens | Required integer. If the agent locks Maximum output tokens, the value must equal the lock; any other value, including 0, returns 400 naming the locked value. Without a lock, the value is sent as given. |
messages | Required and not empty. Each message has role: "user" and non-empty content: a string, or a list of text, image and document blocks. |
stream | true or false. |
mcp_authorizations | See MCP authorizations. |
Any other member, such as system, tools, temperature or metadata, returns 400 with <member> is not permitted on a preset-agent request. Assistant messages, tool_result and other block types, and empty content also return 400. A cache_control on a message block returns 400 with cache_control is not permitted on a preset-agent request. A message is read as decoded: with duplicate members, the last one counts, and member names match in any letter case, so {"role":"assistant","role":"user"} is a user message. The request is checked after the agent is authorized and before the model is called.
The response's model is the agent ID. The gateway runs the agent's tools itself and returns their activity as gateway tool blocks. Usage is reported against the agent's model, with the agent recorded alongside it. Preset agent requests are stateless, like every Messages request.
Output guardrails
When the agent has output guardrails, the gateway holds back all intermediate output and releases only the final answer the guardrails selected:
- The response contains the selected answer as
textblocks. Thinking, tool calls and tool results are never returned, and the gateway runs the agent's tools privately. - A streamed response sends
message_startandpingevents until the answer is selected, then the whole answer as text blocks numbered from0, thenmessage_deltaandmessage_stop. - An allowed answer keeps its stop reason, such as
end_turn,max_tokensorrefusal. A blocked answer is replaced by the agent's block message withstop_reason: "end_turn". - A failed model turn returns an error, or one
errorevent in a stream, with no content. - Your own tools cannot be declared, since agents accept no
tools. When the gateway's capacity for guarded requests is full, the model is not called, as on the Responses API. A request that does not stream returns413withrequest_too_large. A streamed request has already returned HTTP200, so it sendsmessage_startand then anerrorevent withrequest_too_large.
MCP authorizations
mcp_authorizations is a gateway extension, not part of the Anthropic API. It carries OAuth tokens for MCP tool servers that need a user sign-in, keyed by server name, in the same format as on the MCP endpoint:
"mcp_authorizations": {"github": {"access_token": "<token>"}}
It is accepted for preset agents and for direct models. With the Anthropic Python SDK, pass it in extra_body. A malformed entry, a duplicate member or an unknown field returns 400 without repeating the token. For a preset agent, a token that also appears in the messages or in a forwarded setting fails the request with 400 before the model is called, and every token must belong to one of the agent's OAuth servers. A model value that contains one of your tokens returns 400 with the message model must not contain an MCP credential, before the gateway looks the model up.
When a tool server needs a sign-in, the error object is the gateway's mcp_auth_required recovery object inside the Messages error envelope, {"type": "error", "error": {...}}. A missing token returns 400, and a token the server rejected returns 424. After a stream has started, the same object arrives in an error event.
Capability matrix
What a request can contain depends on the target. A preset agent runs on an Anthropic or a Responses model; its column lists what the agent request itself accepts.
| Request member or block | Anthropic model | Responses model | Preset agent |
|---|---|---|---|
model, max_tokens, messages, stream | Supported | Supported | Supported; max_tokens must match a lock |
mcp_authorizations | Supported | Supported | Supported |
system | Supported | Supported | 400 |
temperature, top_p | 400 | Supported | 400 |
top_k | 400 | 400 | 400 |
stop_sequences | Supported | Empty list only | 400 |
thinking | Supported | 400 | 400 |
output_config | Supported | Supported | 400 |
tools, tool_choice | Supported | Supported | 400 |
metadata.user_id | Supported | 400 | 400 |
web_search_20250305 and web_fetch_20250910 tools and their blocks | Supported | 400 | 400 |
mcp_servers, service_tier, other members | 400 | 400 | 400 |
User text, image, document blocks | Supported | Supported | Supported |
User tool_result blocks | Supported | Supported | 400 |
| Assistant messages and their blocks | Supported | Supported | 400 |
cache_control | Supported | 400 | 400 |
citations on assistant text blocks | Supported | 400 | 400 |
citations on other blocks, other block types | 400 | 400 | 400 |
| Output | Anthropic model | Responses model | Preset agent |
|---|---|---|---|
text blocks | Yes | Yes | Yes |
thinking, redacted_thinking blocks | Yes | thinking with a cmgw. signature | Yes, unless guarded |
tool_use blocks | Yes | Yes | No |
cm_gateway mcp_tool_use and mcp_tool_result blocks | Yes | Yes | Yes, unless guarded |
Web search and web fetch blocks, text with citations | Yes | No | No |
| Streaming | Yes | Yes | Yes; a guarded answer arrives whole at the end |
Response
The response is a Messages message object:
{
"id": "msg_…",
"type": "message",
"role": "assistant",
"model": "YOUR_MODEL_ID",
"content": [{"type": "text", "text": "Paris is the capital of France."}],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 21,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"output_tokens": 9
}
}
model is the model ID you sent. stop_reason is one of:
| Stop reason | Meaning |
|---|---|
end_turn | The model finished its answer. |
max_tokens | The answer reached max_tokens. content holds the partial answer. It can end with a tool_use block that was cut off: its input holds only the members the model completed, and in a stream its input_json_delta events hold the partial JSON. Check stop_reason before you run a call. A call to a gateway tool that was cut off before its arguments were complete is never run, and neither is any other gateway call of that turn. Without output guardrails, a unary request then returns 502 with api_error, and a stream ends with an error event. With output guardrails, the call stays private and the response holds the answer the guardrails selected, or the block message. |
stop_sequence | The model produced one of your stop_sequences. stop_sequence holds the matched string; it is null for every other stop reason. Only Anthropic models accept stop sequences. |
refusal | The model refused. content holds any text the model wrote before it refused, then the refusal explanation as a text block when the model gives one. A model turn that both refuses and calls one of your tools returns an api_error instead, before any gateway tool in that turn runs: 502 for a unary request, an error event in a stream. |
pause_turn | Anthropic paused a turn that uses web search or web fetch. See Web search and web fetch. |
tool_use | The model called your tools. content holds their tool_use blocks. Text, or the results of gateway tools the model called in the same turn, can follow them, so check every block, not only the last one. Run each tool_use block; never run an mcp_tool_use block, which the gateway already ran. |
Any other ending, such as a model failure or a stop reason this API cannot represent, returns an error instead of a message.
usage.input_tokens counts input that was not read from or written to the prompt cache. Cache writes and reads are reported separately; your usage accounting counts all three as input. An input_tokens or output_tokens count the model's backend did not report is 0, because the Anthropic SDKs require numbers there. A cache count the model's backend did not report is null rather than 0. Whether a count is reported depends on the model's backend and the request; many Responses backends do not report cache writes. Usage covers every model turn of the request, including turns that called gateway tools. For web search and web fetch counts, see Web search and web fetch.
Streaming
Set "stream": true to receive the message as server-sent events, in the Messages streaming format:
message_startwith an empty message. Itsusagecounts are placeholders: token counts are0and cache countsnull.- For each content block,
content_block_start, itscontent_block_deltaevents andcontent_block_stop.indexcounts the blocks of the response. Text arrives astext_delta, thinking asthinking_deltafollowed by onesignature_delta. Aredacted_thinkingblock arrives whole in itscontent_block_start. Atool_useblock starts withinput: {}, and its input arrives asinput_json_deltaevents whosepartial_jsonstrings join into the input's JSON text. Anmcp_tool_useorserver_tool_useblock streams the same way, and anmcp_tool_result,web_search_tool_resultorweb_fetch_tool_resultblock arrives whole in itscontent_block_start. Atextblock's citations arrive ascitations_deltaevents. Gateway tool blocks arrive as each turn and its tool calls finish, before the answer is complete. To accumulate MCP blocks with the Anthropic Python SDK, see Gateway tools. message_deltawithstop_reason,stop_sequenceand the finalusage, totaled over the whole request and equal to the unary response's, thenmessage_stop.
With the Anthropic Python SDK, client.messages.stream() sends the request with stream set and accumulates the events:
with client.messages.stream(
model="YOUR_MODEL_ID",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
) as stream:
for text in stream.text_stream:
print(text, end="")
message = stream.get_final_message()
The gateway sends ping events while the model is silent. The blocks, stop reason and usage you accumulate from the stream equal the unary response for the same answer, with two exceptions: a refusal from an Anthropic model, described below, and the following case. When a Responses model sends a reasoning item only in its finished response, after answer text has already streamed, the stream delivers that thinking block after the text, while the unary response keeps the model's order. The block's thinking and signature are the same in both. The gateway has not confirmed that a model accepts the reasoning when it is sent back in this changed order.
With an Anthropic model, each block's signature_delta and content_block_stop arrive when the model finishes that block, before message_delta. A finished block is not final until the message ends, because the model can still refuse after it. Check the stop_reason in message_delta before you run a tool_use call or send thinking back. If the stream ends with a refusal or an error event, don't use the earlier blocks. When an Anthropic model refuses, the stream and the unary response both hold the text written before the refusal. Thinking already streamed also stays in the stream, while the unary response leaves it out. A thinking block that finished before the refusal keeps the signature it already received, and a block cut off by the refusal has none. A tool_use block streamed before the refusal cannot be withdrawn, so the stream ends with an error event, while the unary response leaves the call out and returns the refusal. If deltas for an earlier block follow the start of a later one, accumulate deltas by index, as the Anthropic SDKs do. The Anthropic TypeScript SDK 1.3.0 stream helpers dispatch per-event callbacks to the last block. When each block finishes before the next one starts, the callbacks are correct. When deltas for an earlier block follow the start of a later one, the text and thinking callbacks do not fire for those deltas, the signature callback does not fire for that earlier thinking block, and contentBlock reports the last block. finalMessage() and the accumulated message are correct in both cases.
Errors found before the stream starts, such as an invalid request or a denied model, return an ordinary JSON error with its HTTP status. An error after the stream has started ends it with one error event carrying the same error object, and no message_stop. The stream starts before the gateway calls the model, so when the model service rejects the request, for example with 429, the stream ends with an error event: the HTTP status is already 200, and no Retry-After header is sent. If the client disconnects, the gateway stops the model request.
An answer can take longer than 10 minutes. The gateway ends a model turn only when the model sends nothing for 10 minutes or the turn lasts 2 hours, with or without "stream": true. See Response time limits for what the client receives.
Conversation history
The endpoint is stateless. It stores no conversation and creates no conversation items. To continue a conversation, send the earlier messages again, including assistant content exactly as you received it.
Assistant thinking and redacted_thinking blocks must be sent back unchanged. Gateway-added context, such as the description of the tools the model may call, is part of the model input but is not returned. If that context changes between requests, the model may reject earlier thinking.
Thinking from Responses models
Messages has no field for the reasoning items that OpenAI Responses models return. The gateway returns each one as a thinking block: its thinking is the reasoning summary followed by the reasoning text, separated by blank lines, and its signature starts with cmgw. and carries the reasoning item. Send the block back unchanged; the gateway restores the original reasoning item for the model. A cmgw. signature is not an Anthropic signature: sending it to an Anthropic model returns 400. A malformed cmgw. signature also returns 400.
Errors
Errors use the Messages error shape:
{"type": "error", "error": {"type": "invalid_request_error", "message": "max_tokens is required"}}
| Status | error.type |
|---|---|
400 | invalid_request_error |
401 | authentication_error |
403 | permission_error |
404 | not_found_error |
413 | request_too_large |
429 | rate_limit_error |
529 | overloaded_error |
| Other | api_error |
A missing or invalid credential is rejected before the request reaches the gateway and does not use the Messages error shape: a missing or unrecognized credential returns 403, and a recognized API key that is invalid returns 401.
When the model service rejects a request that does not stream, the gateway returns its status with the public message described in Model backend errors, and forwards a Retry-After header. Provider messages are not returned.
When the model service fails after it started answering, the gateway returns the same public message. An invalid request, including one too long for the model, returns 400; an authentication failure 401; a permission failure 403; and a rate limit 429, without a Retry-After header. Any other failure returns 502 with api_error.