> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Warnings

> The Gateway warnings array: every warning code Gateway emits, the surfaces that emit it, and which frame carries warnings on each surface.

A `warnings` array means Gateway served your request but changed it, such as removing a tool the route can't run or adjusting a reasoning level it doesn't accept. Log it wherever you measure cost or quality. Requests that don't run at all are [errors](/merge-gateway/errors).

```json
{
  "warnings": [
    {
      "code": "reasoning_effort_adjusted",
      "message": "reasoning effort 'max' was adjusted to 'xhigh': the highest level the resolved route accepts",
      "detail": {
        "requested_effort": "max",
        "applied_effort": "xhigh",
        "model": "moonshot/kimi-k3",
        "vendor": "baseten"
      }
    }
  ]
}
```

Branch on `code`; `message` is for humans. `detail` is optional with keys that vary by code, so read it defensively. On a clean request the field is absent or `null`, never an empty array.

## Warning codes

| `code`                                | Surfaces               | Meaning                                                                                                                                                                                                                                                                                  |
| ------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reasoning_effort_adjusted`           | All                    | The requested effort isn't one the route accepts, so the closest level ran. `detail.applied_effort` is `null` when the route has no effort control. See [Reasoning](/merge-gateway/capabilities/reasoning).                                                                              |
| `reasoning_effort_policy_bound`       | All                    | The routing policy's effort bounds for the model changed the effort you asked for                                                                                                                                                                                                        |
| `reasoning_exhausted`                 | All                    | The model billed output tokens but returned no content, usually because reasoning used the whole budget. The response is still a `200`, with `finish_reason` `max_tokens` on native `/v1/responses` (`length` on OpenAI-compatible surfaces). Raise the token limit or lower the effort. |
| `reasoning_summary_unavailable`       | All                    | `reasoning.summary` wasn't returned, because the output budget was too small or ran out, or the OpenAI model doesn't reason. `detail.reason` says which.                                                                                                                                 |
| `cache_control_ignored`               | All                    | The route can't honor your cache markers, so they were removed. `detail` names the `vendor` and `prompt_caching_mode`. See [Prompt caching](/merge-gateway/capabilities/prompt-caching).                                                                                                 |
| `server_tool_iteration_limit_reached` | All                    | A [web search](/merge-gateway/capabilities/web-search) loop hit its limit of 6 iterations, so the model answered from the results it had. `detail.max_iterations` is `6`.                                                                                                                |
| `web_search_remapped`                 | All                    | A vendor-hosted search tool ran as `merge:web_search` under your organization's web search mode. `detail` lists `remapped_tools` and `web_search_mode`.                                                                                                                                  |
| `openai_fields_ignored`               | `POST /v1/responses`   | OpenAI-only fields with no native equivalent were ignored. `detail.ignored_fields` lists them. Call `/v1/openai/responses` or send `X-Merge-Wire-Format: openai` instead. See [OpenAI Responses API clients](/merge-gateway/api-overview#openai-responses-api-clients).                  |
| `tools_dropped`                       | `/v1/openai/responses` | Custom tool types the route can't express were removed. `detail.dropped_tools` names them.                                                                                                                                                                                               |
| `tools_mapped`                        | `/v1/openai/responses` | A custom tool was sent as a function tool, so its grammar isn't enforced. `detail.mapped_tools` names them.                                                                                                                                                                              |
| `openai_tool_search_dropped`          | `/v1/openai/responses` | The route moved off OpenAI after the request was accepted, so `tool_search` was removed and every deferred tool was loaded up front                                                                                                                                                      |
| `openai_web_search_dropped`           | `/v1/openai/responses` | OpenAI hosted `web_search` was removed because the route isn't direct OpenAI. Use `{"type": "merge:web_search"}` for search on any model                                                                                                                                                 |
| `openai_image_generation_dropped`     | `/v1/openai/responses` | OpenAI hosted `image_generation` was removed because the route isn't direct OpenAI. Route to an `openai/` model or call `POST /v1/images/generations`                                                                                                                                    |
| `openai_params_ignored`               | `/v1/openai/responses` | The route is served through chat completions, so parameters with no equivalent had no effect. `detail.ignored_params` lists them.                                                                                                                                                        |
| `input_items_dropped`                 | `/v1/openai/responses` | The route is served through chat completions, so replayed reasoning and other items it can't represent were dropped. `detail.dropped_item_types` counts them.                                                                                                                            |

## Where warnings arrive

On SDK-compatible surfaces `warnings` is a Gateway extension that a strict SDK may drop from its typed object, so read it from the raw response or event.

| Surface                          | Non-streaming                            | Streaming                                             |
| -------------------------------- | ---------------------------------------- | ----------------------------------------------------- |
| `POST /v1/responses`             | Top-level `warnings`                     | The terminal `response.done` frame                    |
| `/v1/openai/chat/completions`    | Top-level `warnings`                     | The final chunk                                       |
| `/v1/openai/responses`           | Top-level `warnings`, omitted when empty | Inside `response.completed`                           |
| `/v1/anthropic/v1/messages`      | Top-level `warnings`, `null` when empty  | The final `message_delta`, repeated on `message_stop` |
| `/v1/ai-sdk/chat/completions`    | Top-level `warnings`                     | The final chunk                                       |
| `/v1/ai-sdk/responses`           | Not returned                             | Inside `response.completed`                           |
| `/v1/langchain/chat/completions` | Top-level `warnings`                     | The final chunk                                       |

Non-streaming `/v1/openai/responses` requests that use OpenAI's server-executed `tool_search` return OpenAI's response without `warnings`. Interim stream frames never carry warnings, and a warning raised mid-stream still reaches the terminal frame.

## Next steps

#### [Errors](/merge-gateway/errors)

Every error code grouped by HTTP status

#### [Streaming](/merge-gateway/streaming)

Which frame carries the terminal payload on each surface

#### [Reasoning](/merge-gateway/capabilities/reasoning)

Effort levels per route, and the warning when yours is adjusted