What you will be able to do
- Read stop_reason and the trace to name a failure mode (truncation, refusal, hallucination, under-acting, context loss, format drift, inconsistent output)
- Decide whether a failure starts in the integration layer or in the model's output
- Choose a recovery that removes the cause instead of hiding the symptom
Key concept
Locate the layer before the fix — A bad answer from Claude may come from the model, or from the code that built the request or handled the response. Use the trace and stop_reason to find which layer produced the failure, then apply the fix in that layer.
1.Start with stop_reason, not the reply text
Before you judge the wording of a broken reply, look at the stop_reason field. It tells you why generation ended, and that reason often explains the failure on its own. Every successful Messages API response includes this field. It is not an error code: an HTTP error means the request failed, while stop_reason describes a request that succeeded and then ended in a particular way. So a cut-off answer, an empty answer and a declined answer can all reach your application as normal 200 responses.
When you diagnose, read the field first and the text second. A reply that stops mid-sentence and a reply with no content at all look different on screen, but neither is a model failure until stop_reason says so. A value of max_tokens points at your request configuration. A value of refusal points at a classifier decision. A value of end_turn on an empty reply usually points at how your code formatted the message history. The table lists each value together with how it typically shows up downstream.
| stop_reason | When it occurs | Typical downstream symptom | Cause-level action |
|---|---|---|---|
| end_turn | Claude completed its response naturally | Normal reply, or an empty one if the history pattern told Claude it was done | Use the response; fix message structure if empty |
| max_tokens | The response reached your max_tokens limit | Text cut mid-sentence, JSON that fails to parse, incomplete tool_use block | Raise max_tokens or continue the response |
| tool_use | Claude is calling a tool | Loop stalls if the app treats this as a final answer | Run the tool and return the result |
| pause_turn | A server-tool loop reached its iteration limit | Agent appears to stop partway through a task | Send the assistant content back to continue |
| refusal | Claude declined to respond | Blank output with no error raised | Read stop_details and retry on a fallback model |
| model_context_window_exceeded | The response filled the model's context window | Output cut off even though max_tokens was not reached | Treat the response as truncated |
stop_reason. If it reads max_tokens, the reply hit the limit you set. If it reads model_context_window_exceeded, the response filled the context window. Either way, treat the output as truncated.
Checkpoint 1 of 8· Match them up
Each symptom below arrived in an HTTP 200 response. Match each stop_reason value to the symptom it typically produces downstream.
Tap a term, then the definition that fits it.
All of these come back as successful responses, so only stop_reason shows which layer to fix. max_tokens and model_context_window_exceeded both mean the output was truncated, but only max_tokens points at your own limit. Refusal points at a classifier decision. An empty end_turn reply points at message formatting, and a tool_use stall points at loop handling.
“model_context_window_exceeded | The response filled the model’s context window. | Treat the response as truncated.”Source: platform.claude.com
Sources1
2.Truncation that looks like a parsing bug
A truncated reply often shows up far from its cause, for example as a JSON parse error in your own code. Suppose a pipeline passes Claude's text straight to json.loads. If generation stops at the token cap, the string ends in the middle of a value and the parser reports an unterminated string. The traceback names your parser, but the parser is not the problem. The evidence that matters is a group of failing calls that all show stop_reason: max_tokens and an output length equal to the configured limit. That pattern means the reply never finished.
The recovery acts on the cause. Raise max_tokens above the largest payload you expect. Then add a check on stop_reason before any parser runs, so that a future truncation is reported as truncation and not as malformed JSON. When the last content block of a truncated response is an incomplete tool_use, continuing does not help: resend the request with a higher limit so the full tool call can be generated.
Several plausible fixes leave the cap in place. Retrying the same request with the same max_tokens runs into the same limit, and keeping whichever reply happens to fit just hides how often the problem occurs. Setting temperature to 0 changes sampling, not length. Forcing the opening brace or validating against a schema fixes format problems, but a reply that was cut off still fails validation. Truncation is a length problem and needs a length fix.
Checkpoint 2 of 8· Check yourself
A nightly extraction job passes Claude's reply straight to json.loads, and about 8% of runs crash with 'Unterminated string'. The trace for every failing call shows stop_reason: max_tokens and output_tokens equal to the configured limit. Which change addresses the cause?
The replies were cut off at the token cap, so the parse error is only a symptom of truncation. A higher limit removes the cause, and checking stop_reason makes any future truncation show up as truncation. Retries, temperature, prefill and schema validation all leave the cap in place.
“max_tokens | The response reached your max_tokens limit. | Raise max_tokens or continue the response.”Source: platform.claude.com
Checkpoint 3 of 8· Exam question
A pipeline parses Claude's reply with json.loads. About 3% of calls fail with 'Unterminated string'. Logs for the failing calls all show stop_reason: max_tokens and an output length equal to the configured limit of 512. What should the team do first?
Correct answer: A — Raise max_tokens above the largest expected payload, then check stop_reason before passing the reply on to json.loads
- A. Correct:
stop_reason: max_tokenswith output length equal to 512 shows the reply was cut off by the cap, so the JSON is incomplete. A larger limit removes the cause, and checking the stop reason first catches any truncation that remains. - B. Incorrect: temperature changes sampling variability, not the output cap, so the replies are still cut at 512 tokens. A schema check on a truncated string fails just as
json.loadsdoes and fixes nothing. - C. Incorrect: the model already produces JSON; the replies fail because generation stops at 512 tokens mid-string. Prefilling the opening brace does not raise the cap, and stripping trailing text cannot restore the missing end of the payload.
- D. Incorrect: the same request with the same limit will be cut off at 512 tokens again whenever the payload is long. Retries burn calls and only succeed when a reply happens to be short enough, leaving the root cause in place.
Sources1
3.Refusals arrive as successful responses
Current Claude models include safety classifiers that can decline a request. When one fires, you get a normal response, not an error. Its content is empty, stop_reason is refusal, and a stop_details object names the policy area. A blank panel with no logged error is the typical result: the client renders the empty content because it has no code path for that stop reason. The failure has two parts. The model declined the request, and the integration layer had nothing to show when that happened.
{
"id": "msg_01XFUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"model": "claude-fable-5",
"content": [],
"stop_reason": "refusal",
"stop_details": {
"type": "refusal",
"category": "cyber",
"explanation": "This request was declined because it could enable cyber harm."
},
"usage": {
"input_tokens": 412,
"output_tokens": 0
}
}Use the response shape to rule out other diagnoses. If the clause had dropped out of context, or the network had lost the reply, you would not see stop_reason: refusal. If the reply had been cut off, stop_reason would read max_tokens and some text would be present. The fix is a branch in the client that checks stop_reason directly. That branch can show the user a message, send the item to a human reviewer, or retry on a fallback model. Do not branch on the text of explanation, because category and explanation can both be null. If a refusal arrives mid-stream, discard any partial output already received.
Retry on a different model, because sending the same request to the same model usually earns another refusal. The reasoning_extraction category is an exception that needs a prompt change instead. It is triggered when the prompt asks Claude to write out its internal reasoning, for example as a scratchpad section or a reasoning field in JSON output. That wording might be in a system prompt, a skill or a tool description, so check all three. Monitoring needs the same awareness: because a refusal is a 200, dashboards built on error rates never count it. The mechanics of fallback routing belong to integration resilience.
Checkpoint 4 of 8· Check yourself
After a release adds a required "reasoning" field to the JSON output schema in the system prompt, many triage requests come back as HTTP 200 with empty content, stop_reason: refusal and stop_details.category: reasoning_extraction. What is the right recovery?
The reasoning_extraction category is the exception to retrying on a fallback model. The prompt itself asked Claude to write out its internal reasoning, so the fix is to change the prompt. Resending to the same model usually gets another refusal, and an alert on error rates never counts refusals because they arrive as 200 responses.
“This category has no recommended fallback model, so change the prompt rather than retry the request.”Source: platform.claude.com
Checkpoint 5 of 8· Exam question
A document-review app sends a contract clause to Claude. The response comes back with stop_reason: refusal and the UI renders a blank panel with no error. Other clauses in the same contract work. What is the best diagnosis and response?
Correct answer: D — The client code has no branch for that stop reason; add one that shows the user a message or sends the clause to a human reviewer
- A. Incorrect: the request reached the model and a response came back with a refusal stop reason, and other clauses from the same contract work. Nothing points to lost context, and resending the contract would not change a refusal on this clause.
- B. Incorrect: a response cut off by the output limit reports
max_tokensas its stop reason. This one reports a refusal, so the model declined to answer rather than running out of room, and a larger limit changes nothing. - C. Incorrect: a response with a stop reason arrived intact, so nothing was lost in transit. A refusal is a finished reply, and retrying with backoff would only repeat it or handle a failure that did not occur.
- D. Correct: the refusal is a normal model outcome flagged by the stop reason, and the blank panel shows the integration has no code path for it. Adding a branch that informs the user or escalates the clause to a person fixes the actual gap.
Sources2
4.Isolating the integration layer from the model
The same symptom can come from different layers, so the first diagnostic question is where the bad input came from. Claude acts only on the message history, tools and documents your code sends. If that payload is wrong, the model may respond reasonably to a broken request, and the result still looks like a model failure.
Here is a worked case. A support bot says the refund window for annual plans is 60 days, but the actual policy is 30. The trace shows the retrieval step returned zero documents and the prompt sent an empty <docs> block. The reply is a hallucination, but the cause is in the integration layer: the model was asked a policy question and given no policy. Your application already knows the hit count before it calls Claude. The direct fix is to check that count in code and route zero-hit queries to a fallback reply or a decline-to-answer prompt. A verification step that re-checks claims against an empty <docs> block has nothing to check against. Extra thinking cannot reason its way to facts that were never provided. A bigger model that recalls the policy from training data is the opposite of grounding. On the prompt side, two instructions back up the gate: tell Claude to use only the provided documents, and give it explicit permission to say it doesn't know.
Tool-calling failures follow the same logic. An empty end_turn reply right after a tool call often means your code added a text block after the tool_result, which teaches Claude that a user message follows every tool result, so it ends its turn. The fix is to send only the tool_result blocks. If that fails, add a continuation prompt in a new user message rather than retrying with the empty response. Compare that with an agent that only suggests edits because the user asked "can you suggest some changes". The symptom is similar, but the cause is in the prompt, not the message structure. The table lists other tool-use symptoms whose cause is in your code or schema, not in the model's judgement.
| Symptom | Likely cause | Fix |
|---|---|---|
| Claude refuses to act on a tool result, or asks the user to confirm instructions that came from it | Your own instructions are being delivered inside the tool_result content | Send instructions in a user turn after the tool_result block; keep the tool result to just the data |
| Claude calls tool A when you wanted tool B | Description ambiguity | Differentiate tools by WHEN to use them, not only WHAT they do |
| Claude calls tools sequentially when parallel would be better | Message history formatting | Send multiple tool_result blocks in ONE user message |
| String comparison on tool inputs fails with newer models | Unicode and forward-slash escaping differs between model versions | Parse with json.loads() or JSON.parse() |
Checkpoint 6 of 8· Match them up
In each trace below, the model reacted sensibly to what your code sent, so the fix belongs in the integration layer. Match each observed behaviour to the change that removes its cause.
Tap a term, then the definition that fits it.
Each symptom looks like a model mistake, but each one comes from how the request was built: where instructions sit, how tools are described, how results are grouped, how inputs are parsed, and what follows a tool_result. Changing that payload removes the cause, while retrying or switching models leaves it in place.
“Move your instructions out of the tool result: send them in a user turn after the tool_result block”Source: platform.claude.com
Checkpoint 7 of 8· Exam question
A support bot answers 'What is your refund window for annual plans?' with '60 days, no questions asked.' The company's policy is 30 days. The trace shows the retrieval step returned zero documents, and the prompt passed an empty <docs> block to Claude. What is the most direct fix for the cause?
Correct answer: C — Check the document count in application code before calling Claude, then send zero-hit queries to a fallback reply or a decline-to-answer prompt
- A. Incorrect: a verification pass can only compare the draft with what is in the
<docs>block, and that block was empty. There is nothing to check the 60-day claim against, so the invented figure goes through unchallenged. - B. Incorrect: extended thinking gives Claude more room to reason, but the 30-day policy was never supplied. Reasoning cannot recover a fact that is missing from the prompt, so the model still produces a plausible guess.
- C. Correct: the root cause is that retrieval returned zero documents and the prompt went ahead anyway. Catching that case in code and either using a fallback or having Claude decline stops an ungrounded answer from being generated.
- D. Incorrect: this company's refund policy is private and not in any model's training data. A larger model would still have nothing to recall and would give a more fluent but equally unfounded answer.
5.Cause-level recoveries for model-output failures
Once the payload checks out, the failure is in the model's output, and each failure mode has its own lever. Choosing the wrong one treats the symptom: a stricter parser does not reduce hallucination, and a lower temperature does not stop drift between formats.
Hallucination with good documents present calls for grounding. Allow Claude to admit uncertainty, restrict it to the supplied material, and for long documents have it extract word-for-word quotes before it answers. To audit an answer, ask for a citation for each claim. Running the same prompt several times also helps, because disagreement between runs is a signal of hallucination. These techniques are covered in depth in grounding and citation. A claim with no supporting record in the trace has the same cause: "all tests pass" when no test tool ran is an unsupported claim. The trace shows the gap, and the fix is to require evidence for each claim.
Under-acting is usually a wording problem. Claude follows instructions precisely, so "can you suggest some changes" can return suggestions when you wanted the edits made. Phrase the request as an action ("Change this function…"), or tell Claude in the system prompt to implement changes by default rather than only suggesting them.
Context loss shows up as instructions or facts that Claude ignores, most often in prompts with large inputs. Placement matters: put long documents near the top, above the query, instructions and examples. A 40-page document placed after the question, with rules buried in the middle, is a layout to fix before you rewrite any rule. Managing context across long sessions is covered in context management.
Format drift means the structure varies from reply to reply even when the content is fine. Define the exact output format with JSON, XML or a template, and include a worked example for Claude to match. The defensive parsing side is covered in structured output. Inconsistent output needs one more point: lowering temperature makes output more conservative, but even at 0 identical inputs can give different outputs across API calls. A difference between two runs at temperature 0 is therefore not proof of an integration bug. Reproduce with fixed inputs over several runs, and judge the spread, not a single pair.
Checkpoint 8 of 8· Check yourself
Retrieval returned the full 60-page supplier contract, and the trace shows it reached the prompt intact. Even so, Claude's summary states a 90-day termination notice period that appears nowhere in the contract. Which change targets the cause of this failure?
The payload was correct, so this is hallucination in the model's output, and the lever for it is grounding: quotes first, then an answer based on them, with permission to admit uncertainty. Temperature and format templates deal with sampling and structure, not invented facts. Recalling terms from training data is the opposite of grounding.
“For tasks involving long documents (>20k tokens), ask Claude to extract word-for-word quotes first before performing its task.”Source: platform.claude.com
Sources
(7)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Unlike errors, which indicate failures in processing your request, stop_reason tells you why Claude completed its response generation.”
↩︎ Start with stop_reason, not the reply text“Treat the response as truncated.”
↩︎ Start with stop_reason, not the reply text“Raise max_tokens or continue the response.”
↩︎ Truncation that looks like a parsing bug“the truncated response contains an incomplete tool use block”
↩︎ Truncation that looks like a parsing bug“so Claude ends its turn to follow that pattern”
↩︎ Isolating the integration layer from the model“add a continuation prompt in a new user message rather than retrying with the empty response”
↩︎ Isolating the integration layer from the model“Check this field to decide whether to use the response as-is, continue the conversation, retry, or fall back to another model.”
↩︎ Key concept“Raise max_tokens or continue the response.”
↩︎ Exam trap 1“model_context_window_exceeded | The response filled the model’s context window. | Treat the response as truncated.”
↩︎ Checkpoint“max_tokens | The response reached your max_tokens limit. | Raise max_tokens or continue the response.”
↩︎ Checkpoint - 2.
“A refusal is a successful HTTP 200 response with stop_reason”
↩︎ Refusals arrive as successful responses“Branch on stop_reason or stop_details.type, not on content or the inner stop_details fields.”
↩︎ Refusals arrive as successful responses“In either case, treat any partial output as incomplete and discard it.”
↩︎ Refusals arrive as successful responses“This category has no recommended fallback model, so change the prompt rather than retry the request.”
↩︎ Refusals arrive as successful responses“A refusal is an HTTP 200, so monitoring built on error rates or 5xx responses never sees it.”
↩︎ Exam trap 2“Re-sending a refused request to the same model usually earns another refusal.”
↩︎ Exam trap 3 - 3.https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinationsOfficial docs
“Explicitly instruct Claude to only use information from provided documents and not its general knowledge.”
↩︎ Isolating the integration layer from the model“Explicitly give Claude permission to admit uncertainty. This technique can drastically reduce false information.”
↩︎ Cause-level recoveries for model-output failures“Inconsistencies across outputs could indicate hallucinations.”
↩︎ Cause-level recoveries for model-output failures“For tasks involving long documents (>20k tokens), ask Claude to extract word-for-word quotes first before performing its task.”
↩︎ Checkpoint - 4.
“Claude is trained to treat instructions inside tool results as potentially untrusted third-party content.”
↩︎ Isolating the integration layer from the model“Move your instructions out of the tool result: send them in a user turn after the tool_result block”
↩︎ Checkpoint - 5.https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practicesOfficial docs
“By default, implement changes rather than only suggesting them.”
↩︎ Cause-level recoveries for model-output failures“Place your long documents and inputs near the top of your prompt, above your query, instructions, and examples.”
↩︎ Cause-level recoveries for model-output failures - 6.https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistencyOfficial docs
“Precisely define the output format you want using JSON, XML, or custom templates so that Claude follows every output formatting element you require.”
↩︎ Cause-level recoveries for model-output failures - 7.
“Even with temperature set to 0, the results will not be fully deterministic, and identical inputs might produce different outputs across API calls.”
↩︎ Cause-level recoveries for model-output failures“Even with temperature set to 0, the results will not be fully deterministic, and identical inputs might produce different outputs across API calls.”
↩︎ Exam trap 4