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:
- Empty — the refusal happened before any output. This is not billed for output.
- Partial — the refusal happened mid-stream. Discard the partial content; it's not a usable answer.
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.
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.| Fact | Detail |
|---|---|
| HTTP status | 200 — not an exception; branch on stop_reason. |
| Content (pre-output) | Empty, not billed for output. |
| Content (mid-stream) | Partial — discard it. |
| Why it declined | Inspect stop_details.category. |
| Danger | Reading content[0] first → IndexError on empty content. |
DIAGRAM The refusal-safe read path
(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}
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
stop_reason == "refusal". Your except block won't catch it; you must branch on the field.content[0] before checking stop_reason. → On a
pre-output refusal, content is empty → IndexError. Always branch first.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.