Validating Claude responses before you use them

1.Read stop_reason before the content

Every successful Messages API response has a stop_reason field that says why Claude stopped generating. It is not an error. Errors mean the request failed, while a stop reason describes a completed generation. A response can be a 200 and still be unusable as an answer. Have your pipeline branch on stop_reason before it reads the content. That one field decides whether you use the response, continue it, retry it or send it to another model.

if response.stop_reason == " ? ":
    # Process the complete response
    for block in response.content:
        if block.type == "text":
            print(block.text)

Sources1

2.Truncated, tool and paused turns

Three stop reasons mean the work isn't finished. With max_tokens and model_context_window_exceeded the output was cut off. Text that ends mid-thought is a fragment, not an answer, and it should never reach a parser or a user as if it were complete. You can usually continue a truncated text response. Tool calls are the exception: if the last content block is an incomplete tool_use, continuing won't produce usable arguments. Send the request again with a higher max_tokens.

# Check if response was truncated during tool use
if response.stop_reason == "max_tokens":
    # Check if the last content block is an incomplete tool_use
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Send the request with higher max_tokens
        response = client.messages.create(
            model="claude-opus-5-5",
            max_tokens=4096,  # Increased limit
            messages=messages,
            tools=tools,
        )

tool_use means Claude is waiting for you. Run the tool and return its result. A server tool call that doesn't have its result block yet completes in a later response, so you don't answer it yourself. pause_turn means a server-tool loop hit its iteration limit. Send the assistant content back as it is, and Claude continues from where it stopped.

Sources1

3.Refusals arrive as successful responses

Claude Fable 5.1, Fable 5, Opus 5.5, Opus 5 and Sonnet 5.5 include safety classifiers that can decline a request. A decline comes back as an ordinary response, so a pipeline that only catches exceptions will miss it. A loop that reads response.content[0] will crash on an empty list. A refusal looks like this:

  "content": [],
  "stop_reason": "refusal",
  "stop_details": {
    "type": "refusal",
    "category": "cyber",
    "explanation": "This request was declined because it could enable cyber harm."
  },

Branch on stop_details.category, not on the explanation. The explanation text isn't stable, so show it to people and don't parse it. Both fields can be null when a refusal doesn't map to a named category, and that is a normal, permanent value. A refusal can also come mid-stream, after some output has already arrived. Discard that partial output rather than keeping it. To recover, send the same request to another Claude model. The beta fallbacks="default" setting does this on the server side, using the fallback model recommended for the refusal's category.

Sources2

4.Guard against empty content

A response can end with end_turn and still contain nothing. [Empty end_turn responses](lesson:4.1) usually appear after tool results, when Claude decides the turn is over. In a validation pipeline, that means end_turn alone isn't a passing check. Put the guard next to the stop-reason branch: if response.stop_reason == "end_turn" and not response.content:. Then handle that case explicitly instead of passing an empty list to a parser.

The recovery is the part people get wrong. Sending the conversation back unchanged gets the same empty answer, because Claude has already decided it is done. First fix the message structure, so there are no text blocks straight after tool results. Only if that doesn't work, add a continuation prompt in a new user message.

Sources1

5.Well-formed output is not correct output

A schema guarantees shape, not truth. Constrained decoding makes total_amount a float. It doesn't make it the total printed on the invoice. Fluent, well-formed text can still be wrong because of how [next-token generation and hallucination](lesson:5.1) work. A confidence: 0.92 field is also model output, constrained to be a number and nothing more. Treat confident, valid output as a claim to check against your sources.

Several grounding and verification techniques turn that check into steps your pipeline can run:

- Quote first: for long documents, have Claude extract word-for-word quotes before doing the task, and base the analysis only on those quotes. - Cite and retract: require a supporting quote for each claim, and remove any claim that has no quote. - Best-of-N: run the same prompt several times and compare the results. Inconsistencies across outputs could indicate hallucinations. - Allow uncertainty: give Claude explicit permission to say it doesn't have enough information, so it doesn't fill the gap. - Restrict knowledge: tell Claude to use only the provided documents and not its general knowledge.

Quotes are what make this something code can verify. If the schema asks for the supporting quote next to each extracted value, your validator can check that the quote really appears in the source document before it accepts the record.

Sources3

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.A refusal raises an API error, so try/except around the call is enough to catch it.Why is that wrong?

   A refusal is a successful 200 response with stop_reason "refusal" and possibly empty content. Only a stop_reason check catches it.

   Covered in Refusals arrive as successful responses

2. 2.Any max_tokens stop can be fixed by asking Claude to continue.Why is that wrong?

   When the truncated content ends in an incomplete tool_use block, the request has to be retried with a higher max_tokens to get the full tool call.

   Covered in Truncated, tool and paused turns

3. 3.Output that passes schema validation can be trusted as factually correct.Why is that wrong?

   Schema compliance only constrains shape. Claude can still produce content that is factually wrong or inconsistent with the context, so claims need grounding and citation checks.

   Covered in Well-formed output is not correct output