“`stop_reason`: `pause_turn`” — a 10-iteration limit that is not in your config

"stop_reason": "pause_turn"

That is not an error and nothing failed. Claude’s own server-side tool loop — the one that runs web search or web fetch inside a single request, without your code in the circuit — hit its iteration ceiling mid-task and handed the half-finished turn back to you. The fix is not to raise a cap. The fix is to send the response back to the API unchanged.

In ten seconds. Every other stop on this site is a cap your framework counts. This one is counted by Anthropic, inside one HTTP request, and the documented default is 10 iterations. You will not find it in your agent config because it is not in your agent config.

Do not retry the prompt and do not raise max_tokens. Append the assistant message you just received to messages and call the API again. Claude picks the task up where it stopped.

What the documentation says, quoted

From Stop reasons and fallback, the section headed pause_turn:

Returned when the server-side sampling loop reaches its iteration limit while executing server tools such as web search. The default limit is 10 iterations per request. When this happens, the response may contain a server_tool_use block without a corresponding result block. To let Claude finish processing, continue the conversation by sending the response back as-is.

Four separate facts are in those four sentences, and the order matters. The loop is server-side: it is Anthropic’s loop, not yours. Its limit is per request, so it resets on the next call and a long task simply takes several. The response you are holding may contain a server_tool_use block with no matching result block, which is why naive code that walks content looking for finished tool results finds a dangling one and throws. And the instruction is to continue the conversation by sending the response back as-is — not to summarise it, not to re-ask, not to strip the incomplete block out.

The sentence that tells you this is not your tool call

The same page draws the line between the server loop and your loop explicitly:

A response that leaves a client tool_use block waiting on you never has a stop_reason of pause_turn: when Claude stops to call your tools, stop_reason is tool_use, and you continue it by sending the client tool_result blocks instead of the response itself.

This is the single most useful line in the section, because the two cases look identical from a log line that prints only “the run stopped with a tool block pending”. They are handled in opposite ways. On tool_use you run something and send a tool_result back. On pause_turn you run nothing and send the response object itself back. Send a tool_result for a paused server turn and you are answering a question nobody asked; send the response object back for a client tool_use and Claude sits waiting for the result you never computed, which is one of the ways a loop burns its whole turn budget doing nothing.

What it costs you to get this wrong

The same page gives the failure mode in the vendor’s own words, as the error the API returns when the unresolved server tool call is dropped rather than continued:

`web_search` tool use with id `srvtoolu_01HxbWnMRmbWyMfUtJKC45rA` was found without a corresponding `web_search_tool_result` block

That arrives as a 400 invalid_request_error. Note what it means for your retry logic: a 400 is not a transient failure and a backoff-and-retry wrapper will keep sending the same malformed conversation until it gives up, billing every attempt. The documentation also records the neighbouring case — omitting a client tool_result, or putting one after other content, fails earlier with the standard tool_use ids were found without tool_result blocks immediately after error instead. Two different errors, two different causes, and the only way to tell which conversation you have built is to have read stop_reason before you built it.

Why this one is invisible in your framework config

Every ceiling with a page on this site is a number you can find in your own code: request_limit, recursion_limit, max_turns, max_llm_calls. You can grep for them. You can raise them. Raising the cap moves the wall is about exactly that reflex.

There is nothing to grep for here. The 10 is Anthropic’s, it is spent inside one HTTP request, and your agent framework never sees it — from the framework’s point of view that was one model call that returned successfully. So an agent that uses server-side web search and quietly loses work has a ceiling your instrumentation is not counting, on top of the one it is. If you are debugging a run that died well short of its timeout, this is a candidate that no amount of reading your own config will turn up.

The handler

The documentation’s own best-practice section is a single dispatch on the field, and it treats all five cases as things you are expected to have written code for:

match response.stop_reason: case "tool_use": return handle_tool_use(response) case "max_tokens": return handle_truncation(response) case "model_context_window_exceeded": return handle_context_limit(response) case "pause_turn": return handle_pause(response) case "refusal": return handle_refusal(response)

Three things worth doing in handle_pause, in this order:

Append and re-call, do not re-prompt. Push the assistant message onto messages exactly as it came and make the next request. Anything you add or remove is a change to a conversation Claude is in the middle of.
Bound the resumptions and count them. The server limit resets per request, so a task that needs forty search iterations will pause four times and will keep pausing. That is a loop, and an unbounded resume is a runaway. Give it a maximum, and log the count — a run that pauses nine times is telling you something about the task that you want to know.
Persist what has already landed. The paused response contains real completed work. A resume that fails should not also lose the three searches that succeeded.

The documentation frames the field itself as something present on success rather than on failure: stop_reason “is part of every successful Messages API response. Unlike errors, which indicate failures in processing your request, stop_reason tells you why Claude completed its response generation.” Which is the whole reason this one is missed: nothing throws, the HTTP status is 200, and a wrapper that only inspects exceptions sees a clean call.

Provenance

One document, for this page: Stop reasons and fallback in Anthropic’s own API documentation — 2,208,588 bytes, HTTP 200, fetched 4 October 2026 for this page. We aimed at docs.claude.com and were redirected once, so the bytes quoted here were served by platform.claude.com; that is the host we read and the host we checked for permission before reading it. Every sentence shown in a quote block above is from that fetch. The page carries no publication or revision date of its own, so we do not give one. We did not read the Messages API reference, the SDK source, or any other page on that host, and nothing here describes them.

There is a written guide: the stop-reason dispatch above as a table you can hold against your own handler, the bounded-resume loop that keeps a paused server turn from becoming a runaway, and the arithmetic for telling which of five ceilings ended a run from the evidence a 200 response actually carries.

No page on this site has a checkout widget of its own. There is a written guide behind this host and it is on sale at $19 on a storefront that delivers the files automatically and carries a 30-day money-back guarantee: buy it there; the guide can also be paid for with 19 USDC on Base at the payment page, where delivery is by hand as a reply to your email. Every page on this site, including this one, is free to read in full, with no sign-up and nothing gated.

The short version: pause_turn means Anthropic’s server-side tool loop hit its iteration limit — documented default 10 per request — while running a server tool such as web search. Nothing failed; the status is 200. Do not retry and do not raise a cap: append the assistant message you received to messages unchanged and call again. If a client tool_use block is what is pending, the stop reason is tool_use and not this, and you answer it with a tool_result instead. Bound your resumes, count them, and write finished work to disk before each one.

Nearby

stop_reason: model_context_window_exceeded — the sibling value on the same field, and the one that tells you the context window stopped the response rather than any turn cap.
max_turns vs timeout vs context window — the three things a limit can count. The limit on this page is a fourth, counted by the vendor inside one request.
recursion_limit, max_iter, max_turns: one wall under several names — why the reflex to raise the number is usually the smaller half of the fix.
Why an agent run dies before its timeout — the other ceilings that fire while your clock still has room on it.
Reached maximum number of turns — how to tell a cap set by your loop library from a cap set by something above it.

This page counts anonymous readership, and it carries one counter rather than the two that the older pages on this host carry. Each load sends the page path, the address of the page you came from, how long the page was open, whether you scrolled, and any campaign or outreach code in the link you followed; a second “engaged” event is sent once, ten seconds after the page opens — whether or not the tab is in front of you — or as soon as you scroll a quarter of it. The campaign codes from the first link you arrived on are kept in this browser’s local storage, and a later visit that arrives with no codes of its own is counted against them; a link carrying its own codes is used for that visit, and the stored first touch is never replaced. An outreach code is removed from the address bar after it is read. Because this page sends one view event rather than two, a view count taken from it is directly comparable to a load, which is not true of the eighteen pages published before it — those send two, and any rate measured against them reads half its true value. No name is attached to any of this: the only identifier the code can send is an outreach token minted per recipient, and no link carrying one has ever been sent for this page. No cookie; the local storage above does that job. The page also asks this domain for an analytics script at /_vercel/insights/script.js; on 26 September 2026 that address returned HTTP 404 on every host we publish, so no script from another company was served or ran — the page goes on asking, so this stops being true the moment that address starts answering, without a byte of this page changing. Your browser and the network attach things the page does not send: the identification string your browser gives, your IP address and the time of the request. The host that serves this page keeps its own request logs; those are its record and not ours.

“stop_reason: pause_turn” — a 10-iteration limit that is not in your config