What happens when Claude exceeds the configured search limit?

Definition: Anthropic's max_uses parameter caps the number of web searches in one API request. If Claude attempts another search after that cap, the API returns a successful 200 response whose body contains a web_search_tool_result_error object with error_code: "max_uses_exceeded".

Key facts

• Anthropic's web search documentation says the tool gives Claude access to real-time web content and returns citations for sources drawn from search results.
• The max_uses parameter limits the number of searches performed for a request. An attempt beyond that setting becomes an error result.
• When a search error occurs, content is one error object rather than a list of result blocks. An empty content list represents a successful search with no matches.
• Each web search counts as one use regardless of the number of results returned, and a search that errors is not billed.

What does max_uses_exceeded look like?

Anthropic documents the error as a web_search_tool_result block. The block keeps the tool_use_id for the server call and places the error type and code in its content object.

{
  "type": "web_search_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_search_tool_result_error",
    "error_code": "max_uses_exceeded"
  }
}

The same documentation says that the Claude API still returns 200 when the web search tool encounters an error. A handler should therefore inspect the response body for the result block and its nested error_code, rather than treating the HTTP status alone as the search outcome. The object-versus-list distinction also matters when parsing a response: an error has one object in content, while a successful search with no matches has an empty list.

Does the application send a tool_result block?

Anthropic's server tools documentation says that server tools run internally. The call and result appear in the response, the application does not handle execution, and it does not need to send a tool_result for that server call. For web search, the web_search_tool_result block follows the server_tool_use block in the same assistant turn and is paired by tool_use_id.

That means max_uses_exceeded is data to inspect in the returned server result. It is different from a client tool call, where the application executes the operation and sends a user message containing a matching tool_result block. If Claude calls a server tool and a client tool in the same parallel group, the server result can be absent from that response, the response ends with stop_reason: "tool_use", and the API runs the server tool after the client result is returned.

How is this different from pause_turn?

Anthropic describes pause_turn as a stop reason for a long-running server-side search loop. The continuation is a new request that sends the paused assistant message back unchanged and keeps the same tools. A continued turn can pause again, so the client checks stop_reason on each response.

max_uses_exceeded is instead an error code inside a web_search_tool_result block. The two signals should be handled from their documented locations: inspect the result block for the search error, and inspect stop_reason for a paused turn. Anthropic also states that a server tool call whose result already appears in the same response needs nothing from the client.

How should max_uses be configured?

The limit is part of the web search tool definition. Anthropic's example uses the web_search_20250305 tool with max_uses set to 5:

{
  "type": "web_search_20250305",
  "name": "web_search",
  "max_uses": 5
}

The documentation presents max_uses as a hard cap for one request. Its guidance gives different search counts for simple factual queries and for comparative or multientity research, so the configured value determines when the error can occur.

Related terms

• Claude web search
• Agentic search
• Claude-SearchBot

FAQ

Is max_uses_exceeded a 400 request error?

No. Anthropic documents web search errors inside a 200 response. A 400 validation error is documented for a different case: sending search results onward with missing or modified encrypted_content.

Should a client add a tool_result after this error?

No client result is required for the direct server-tool result. The server tools documentation says the API executes the tool internally and that the application does not respond with a tool_result for it.

Does an empty result list mean the limit was exceeded?

No. Anthropic distinguishes an empty content list, which is a successful search with no matches, from a single error object whose code is max_uses_exceeded.

Sources

1. Anthropic, "Web search tool", n.d.
2. Anthropic, "Server tools", n.d.

---

Check how a page reads to answer engines. Open the GEO score analyzer