Can a Claude search tool failure arrive in a successful HTTP response?

Definition: Yes. As of 17 October 2026, Anthropic documents that a web search tool error can arrive in a 200 response, with the failure represented inside the response body as a tool result error.

Key facts

• Anthropic's web search tool documentation says that a web search error, including a rate limit event, still produces a 200 success response.
• The documented error block has type web_search_tool_result, a tool_use_id, and a nested web_search_tool_result_error object with an error_code.
• When a search fails, content is one error object. A successful search with no matches uses an empty content list.
• Anthropic's Claude API errors documentation describes a separate JSON shape for API errors, with a top-level error object and a request_id field.
• The HTTP Semantics standard defines the 2xx class as a request that was successfully received, understood, and accepted.

What does “successful” mean in this response?

The word “successful” describes the outer HTTP exchange. The HTTP standard assigns 2xx to requests that were successfully received, understood, and accepted. Anthropic's web search documentation applies that meaning to the 200 response while describing a separate outcome inside its body.

The result of the search tool is therefore a content-level event. A client that treats every 200 as proof that search returned usable results can miss the nested error object. The response needs two checks: the HTTP status and the content blocks that describe the server tool call and its result.

What does the documented tool error look like?

Anthropic gives max_uses_exceeded as an example. The max_uses setting limits the number of searches Claude may perform. If Claude attempts more searches than allowed, the documentation says that the web_search_tool_result is an error with this code.

The response example is:

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

The tool_use_id connects the result to the tool invocation. The nested type identifies the result as an error, and error_code gives the documented reason. Anthropic also lists too_many_requests as an error code for a rate limit exceeded condition.

How should a client classify the result?

A parser should preserve the HTTP status and inspect the response content. For a web search result block, a nested content.type of web_search_tool_result_error indicates a tool failure even when the HTTP status is 200. A normal result has result blocks; a search with no matches has an empty content list, which Anthropic distinguishes from an error.

Anthropic describes web search as a server tool whose call and result appear in the response. The tool_use_id lets a client pair those blocks. If an error occurs during web search, the same documentation says that the search is not billed, while each web search otherwise counts as one use regardless of the number of returned results.

How is this different from an API error?

The API errors page describes request and service failures through HTTP status codes, with a top-level JSON error object. That shape belongs to an HTTP error response. A web search tool failure belongs to the response content described above.

The web search documentation gives a concrete boundary: supplying both allowed_domains and blocked_domains causes the API to return a 400 error. That invalid request is handled at the API level. A search that reaches the tool and then fails can instead produce a 200 response containing web_search_tool_result_error.

Related terms

• Claude web search
• Can Claude web search be limited to specific domains?
• How does Claude web fetch differ from web search?
• Agentic search

FAQ

Should a client retry a 200 response containing a search error?

The sources document the response shape and the error code. They do not prescribe a retry policy for this content-level error, so the client should handle error_code according to its own application policy.

Is an empty result list the same as a failed search?

No. Anthropic distinguishes an empty content list for a search with no matches from a single error object for a failed search.

Does a 400 always mean that the search provider failed?

No. Anthropic documents 400 for invalid request conditions such as sending both domain-list settings. That is different from a tool error represented inside a 200 response.

Sources

1. Anthropic, "Web search tool", undated
2. Anthropic, "Claude API errors", undated
3. IETF, "HTTP Semantics", June 2022

---

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