D1 · Agentic Architecture › Cluster 2 · Stop Reasons

2.5 · refusal & stop_details

A 200 that declines — and may have no content

CONCEPT A refusal is a success-status decline

When a safety classifier or the model itself declines, the API returns HTTP 200 with stop_reason == "refusal". It is not an HTTP error — your try/except around the request won't catch it. You must branch on stop_reason. Critically, the response content may be:

Because content can be empty, reading content[0] without checking stop_reason first will throw an index error. Inspect stop_details.category to learn why it declined.

🔑 Order of operations: (1) check stop_reason == "refusal"; (2) read stop_details.category; (3) only then, if content exists, read it — and if it was mid-stream, discard the partial.
FactDetail
HTTP status200 — not an exception; branch on stop_reason.
Content (pre-output)Empty, not billed for output.
Content (mid-stream)Partial — discard it.
Why it declinedInspect stop_details.category.
DangerReading content[0] first → IndexError on empty content.

DIAGRAM The refusal-safe read path

flowchart TD A([response received · HTTP 200]) --> B{stop_reason == refusal?} B -->|No| N["read content normally
(other branches, 2.1)"] B -->|Yes| C["read stop_details.category"] C --> D{content empty?} D -->|Yes| E["🔴 nothing to read
(pre-output, not billed)"] D -->|No| F["⚠️ mid-stream partial
DISCARD it"] E --> G["report decline · do NOT index content[0]"] F --> G classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; classDef warn fill:#fff3cd,stroke:#ffc107,color:#856404; class N ok; class E,G bad; class F warn;

CODE A refusal-safe read

Branch on stop_reason before touching content[0].

# HTTP 200 even on refusal — no exception is raised. Branch first.
resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024,
    messages=messages,
)

if resp.stop_reason == "refusal":
    # Learn WHY before reading any content.
    category = resp.stop_details.category      # e.g. inspect the reason
    log.warning(f"declined: {category}")
    # content may be EMPTY (pre-output) or PARTIAL (mid-stream) → don't trust it.
    return {"refused": True, "category": category}   # do NOT read content[0]

# Safe only now: stop_reason is not refusal, content is present.
text = resp.content[0].text
return {"refused": False, "text": text}
Anti-pattern: text = resp.content[0].text as the first line after the call. On a pre-output refusal, content is empty and this raises IndexError.

EXAM TRAPS

Trap: Expecting a refusal to be an HTTP error. → It's HTTP 200 with stop_reason == "refusal". Your except block won't catch it; you must branch on the field.
Trap: Reading content[0] before checking stop_reason. → On a pre-output refusal, content is empty → IndexError. Always branch first.
Trap: Using the partial text from a mid-stream refusal. → Discard it. It's not a valid answer, and it can be misleading.
Trap: Ignoring stop_details.category. → That field tells you why it declined; it's what you inspect to decide how to respond or reroute.

PRACTICE

Q1 · Your service throws IndexError on some requests but the HTTP status was 200. Cause?

A refusal. On a pre-output refusal the content is empty, so reading content[0] before checking stop_reason throws IndexError. Branch on stop_reason == "refusal" first.

Q2 · A refusal arrives with some partial text already streamed. Do you show it to the user?

No — discard the partial content. It isn't a usable answer. Report the decline (optionally using stop_details.category) instead.

Q3 · Where do you look to learn WHY the model refused?

stop_details.category. Check it before (and instead of) trusting content, which may be empty or partial.