Do failed Claude web fetch attempts count against max_uses?

Definition: Yes. Anthropic's Web Fetch tool documentation states that failed fetches count against the max_uses limit. When Claude attempts more fetches than the configured limit, the API returns a web_fetch_tool_result error with the max_uses_exceeded code.

Key facts

• Anthropic's Web Fetch tool documentation defines max_uses as the limit on web fetches performed for a request and explicitly includes failed fetches in that count.
• The same documentation says there is currently no default limit. You set the value in the web fetch tool definition.
• A failed fetch is represented inside a 200 response. Claude sees the error result and continues the turn.
• url_not_accessible means that content failed to fetch because of an HTTP error. max_uses_exceeded means the maximum tool uses was exceeded.
• Web Fetch is a server tool. Anthropic's server-tools documentation says the API executes server tools internally and the client does not send a tool_result for a completed server call.

What does max_uses count?

Anthropic defines max_uses as the number of web fetches performed. The sentence immediately following that definition states that failed fetches count against the limit. Therefore, an attempt that produces an error result still consumes one place in the configured fetch allowance for that request. The documentation does not describe a separate retry allowance for failures.

The tool definition places the setting beside the tool type and name:

{
  "type": "web_fetch_20250910",
  "name": "web_fetch",
  "max_uses": 5
}

Anthropic's example uses 5; the reference definition also says the parameter is optional and that the current tool has no default limit. If Claude attempts another fetch after the limit is reached, the result uses the max_uses_exceeded error code.

How does a failed fetch appear in the response?

The Web Fetch page says that a tool error produces a successful HTTP response whose body contains the error. Its example is:

{
  "content": {
    "type": "web_fetch_tool_result_error",
    "error_code": "url_not_accessible"
  }
}

The documented error list separates input and access conditions. It includes malformed input, URLs longer than 250 characters, domain or Anthropic-side restrictions, URLs absent from prior conversation context, HTTP fetch failures, rate limits, unsupported content types, exhausted uses and internal errors. A client should read the nested error_code rather than treating the outer 200 status as a successful content retrieval.

Anthropic's API errors documentation describes a different outer error shape for HTTP API failures: JSON with a top-level error object containing type and message, plus a request_id. A Web Fetch tool failure uses the tool-result shape above, so the two layers are handled separately.

When is a fetch actually executed?

The server-tools page says the API executes a server tool internally and returns its call and result in the response. A direct Web Fetch call therefore produces a result that the client reads without sending a matching tool_result.

Mixed turns have a separate sequence. If Claude calls web_fetch alongside a client tool, the first response can contain a server_tool_use block without a result and end with stop_reason: "tool_use". The API runs the deferred server tool after the client sends its tool_result blocks, with the same tools still defined. Anthropic documents the counting rule for failed fetches, but it does not state whether a deferred mixed-turn call reserves a max_uses slot before that execution.

What should an API client record?

Record the tool_use_id, the nested error_code and the request context. The Web Fetch result format also includes the fetched URL, a document block and retrieved_at for successful results. For failures, the error code identifies the outcome: url_not_accessible is an HTTP fetch failure, while max_uses_exceeded identifies exhaustion of the configured fetch limit.

Related terms

• What happens when Claude exceeds the configured search limit?
• Can a Claude search tool failure arrive in a successful HTTP response?
• How does Claude web fetch differ from web search?

FAQ

Does a failed fetch return an HTTP error status?

Anthropic documents a 200 response with a web_fetch_tool_result_error in the body. The nested error code supplies the tool-level outcome.

Does url_not_accessible mean that max_uses was reached?

No. The documentation lists url_not_accessible for a failed HTTP fetch and max_uses_exceeded for an exhausted fetch-use limit.

Do I send a tool_result after a direct Web Fetch call?

No. Web Fetch is a server tool, so its completed result is returned by the API. A client sends tool_result blocks when a client tool in the same mixed turn is waiting for them.

Sources

1. Anthropic, "Web fetch tool", 17 October 2026
2. Anthropic, "Server tools", 17 October 2026
3. Anthropic, "Claude API errors", 17 October 2026

---

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