Skip to main content
Version: 3.6.1-rc.2

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 invoke access 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​

MemberSupport
modelRequired. A model, model alias or preset agent ID. A preset agent accepts fewer members; see Preset agents.
max_tokensRequired integer. null is rejected. 0 is sent to the model as given.
messagesRequired and not empty. Roles user and assistant. A final assistant message (a prefill) returns 400 unless the model is an Anthropic model.
systemA 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.
metadataOnly user_id. See Prompt caching and user ID.
temperature, top_p, top_k, stop_sequences, thinking, output_configSee Settings.
tools, tool_choiceSee Tools.
streamtrue or false. See Streaming.
mcp_authorizationsA 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​

BlockSupported sourcesSent to a Responses model asSent to an Anthropic model as
imagebase64 with media_type image/jpeg, image/png, image/gif or image/webp; urlinput_image with a data URL or the URLa native image block
documentbase64 with media_type application/pdf; urlinput_file with file_data as a data URL, or file_urla 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.

SettingAnthropic modelResponses model
temperature, top_p400 at any value, including defaults such as temperature: 1.Sent as given.
top_k400 at any value, including 0.400: the Responses protocol has no counterpart.
stop_sequencesSent 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.effortSent as given.Sent as reasoning.effort. The model can still reject a value it does not support; only some models accept max.
output_config.formatSent 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.

RequestSent to a Responses model asSent to an Anthropic model as
A toolA 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, noneauto, noneSent as given
tool_choice anyrequiredSent as given
tool_choice {"type": "tool", "name": …}A named function choiceSent as given
disable_parallel_tool_useparallel_tool_calls with the opposite value. Omitted, it is not sent.true is sent as given; false is the default
Assistant tool_useA function_call with the same ID, name and input as its argumentsA native tool_use block
User tool_resultA function_call_output for the same call IDA 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_domains or blocked_domains (not both), cache_control, strict and allowed_callers. Web search also accepts user_location; web fetch also accepts max_content_tokens and citations. allowed_callers may only be ["direct"]. Any other member, name or tool version returns 400.
  • 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 named web_search or web_fetch is an ordinary client tool. tool_choice can name them.
  • A Responses model or a preset agent returns 400 for these tools and for their blocks in messages.

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 reasonWhat to do next
pause_turnAnthropic 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_useThe 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:

MemberValue
modelRequired. The agent ID.
max_tokensRequired 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.
messagesRequired and not empty. Each message has role: "user" and non-empty content: a string, or a list of text, image and document blocks.
streamtrue or false.
mcp_authorizationsSee 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 text blocks. Thinking, tool calls and tool results are never returned, and the gateway runs the agent's tools privately.
  • A streamed response sends message_start and ping events until the answer is selected, then the whole answer as text blocks numbered from 0, then message_delta and message_stop.
  • An allowed answer keeps its stop reason, such as end_turn, max_tokens or refusal. A blocked answer is replaced by the agent's block message with stop_reason: "end_turn".
  • A failed model turn returns an error, or one error event 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 returns 413 with request_too_large. A streamed request has already returned HTTP 200, so it sends message_start and then an error event with request_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 blockAnthropic modelResponses modelPreset agent
model, max_tokens, messages, streamSupportedSupportedSupported; max_tokens must match a lock
mcp_authorizationsSupportedSupportedSupported
systemSupportedSupported400
temperature, top_p400Supported400
top_k400400400
stop_sequencesSupportedEmpty list only400
thinkingSupported400400
output_configSupportedSupported400
tools, tool_choiceSupportedSupported400
metadata.user_idSupported400400
web_search_20250305 and web_fetch_20250910 tools and their blocksSupported400400
mcp_servers, service_tier, other members400400400
User text, image, document blocksSupportedSupportedSupported
User tool_result blocksSupportedSupported400
Assistant messages and their blocksSupportedSupported400
cache_controlSupported400400
citations on assistant text blocksSupported400400
citations on other blocks, other block types400400400
OutputAnthropic modelResponses modelPreset agent
text blocksYesYesYes
thinking, redacted_thinking blocksYesthinking with a cmgw. signatureYes, unless guarded
tool_use blocksYesYesNo
cm_gateway mcp_tool_use and mcp_tool_result blocksYesYesYes, unless guarded
Web search and web fetch blocks, text with citationsYesNoNo
StreamingYesYesYes; 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 reasonMeaning
end_turnThe model finished its answer.
max_tokensThe 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_sequenceThe 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.
refusalThe 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_turnAnthropic paused a turn that uses web search or web fetch. See Web search and web fetch.
tool_useThe 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:

  1. message_start with an empty message. Its usage counts are placeholders: token counts are 0 and cache counts null.
  2. For each content block, content_block_start, its content_block_delta events and content_block_stop. index counts the blocks of the response. Text arrives as text_delta, thinking as thinking_delta followed by one signature_delta. A redacted_thinking block arrives whole in its content_block_start. A tool_use block starts with input: {}, and its input arrives as input_json_delta events whose partial_json strings join into the input's JSON text. An mcp_tool_use or server_tool_use block streams the same way, and an mcp_tool_result, web_search_tool_result or web_fetch_tool_result block arrives whole in its content_block_start. A text block's citations arrive as citations_delta events. 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.
  3. message_delta with stop_reason, stop_sequence and the final usage, totaled over the whole request and equal to the unary response's, then message_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"}}
Statuserror.type
400invalid_request_error
401authentication_error
403permission_error
404not_found_error
413request_too_large
429rate_limit_error
529overloaded_error
Otherapi_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.