Stop Reasons & Errors

Reliability items hinge on two enumerations: the stop_reason values a loop must branch on, and the HTTP errors a client must classify into retry-or-fix. This page covers every one with cause, detection and handling.

stop_reason — every value

def handle(r, messages):
    sr = r.stop_reason
    if sr == "tool_use":
        messages.append({"role": "assistant", "content": r.content})
        messages.append({"role": "user", "content": run_tools(r.content)})
        return "continue"
    if sr == "max_tokens":
        messages.append({"role": "assistant", "content": r.content})
        messages.append({"role": "user", "content": "Continue from where you stopped."})
        return "continue"
    if sr == "pause_turn":
        return "resend"                 # re-send unchanged
    if sr == "refusal":
        return handle_refusal(r)        # explicit fallback path
    return "done"                       # end_turn / stop_sequence

HTTP errors — every status

Retry?  ── status in {429, 500, 502, 503, 529} ──► YES: exponential backoff + jitter, honour retry-after
        └─ status in {400, 401, 403, 404, 413}  ──► NO: fix the request/credentials/entitlement

import time, random
from anthropic import APIStatusError, RateLimitError, APIConnectionError

RETRYABLE = {429, 500, 502, 503, 529}

def call(fn, **params):
    for attempt in range(6):
        try:
            return fn(**params)
        except RateLimitError as e:
            wait = float(e.response.headers.get("retry-after", 0)) or min(60, 2 ** attempt)
            time.sleep(wait + random.uniform(0, 0.5))
        except APIStatusError as e:
            if e.status_code in RETRYABLE:
                time.sleep(min(60, 2 ** attempt) + random.uniform(0, 0.5))
            else:
                raise                     # 4xx → fix, don't retry
        except APIConnectionError:
            time.sleep(min(60, 2 ** attempt) + random.uniform(0, 0.5))
    raise RuntimeError("exhausted retries")

import { APIError } from '@anthropic-ai/sdk';
const RETRYABLE = new Set([429, 500, 502, 503, 529]);
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

export async function call<T>(fn: () => Promise<T>): Promise<T> {
  for (let attempt = 0; attempt < 6; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err instanceof APIError && RETRYABLE.has(err.status ?? 0)) {
        const ra = Number(err.headers?.['retry-after']) || Math.min(60, 2 ** attempt);
        await sleep((ra + Math.random() * 0.5) * 1000);
        continue;
      }
      throw err; // 4xx → fix
    }
  }
  throw new Error('exhausted retries');
}

Streaming errors

An error event can arrive mid-stream (commonly overloaded_error). Handle it like the HTTP status: retryable overload/timeout → backoff and restart the stream; malformed request → fix.

event: error
data: {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}

Tool execution errors (not HTTP)

A tool that fails is not an API error — the API call succeeded. Return a structured tool_result with is_error: true:

{ "type": "tool_result", "tool_use_id": "toolu_01", "is_error": true,
  "content": "{\"category\":\"not_found\",\"retryable\":false,\"message\":\"No order ORD-999\"}" }

Never return empty success on failure (silent empty-success anti-pattern).

Decision quick reference

Common misconceptions

Scenario walkthrough

An agent on Opus 5 in production intermittently: (a) returns cut-off JSON, (b) hits 529s under load, (c) once returned a safety refusal shown to users as “Error 500”, and (d) an engineer added tool_choice: "any" after switching one flow to Fable 5.1 and now gets 400s.

1. Cut-off JSON — stop_reason: max_tokens. Raise max_tokens and/or continue; validate before use.
2. 529s — retryable; exponential backoff + jitter honouring retry-after; after repeated 529, fall back to a newer-or-equal model (not down).
3. Refusal shown as 500 — stop_reason: refusal was mishandled; route to an explicit fallback message, not a generic error.
4. 400 on Fable 5.1 — forced tool_choice is unsupported (400, not retryable); switch to auto+instruction, strict: true, or output_config.format.

Rejected alternatives: retrying the 400 (client error — fix it), treating truncated JSON as valid (silent failure), and surfacing the refusal as a 500 (refusal-mishandling).

Key takeaways

• stop_reason values: end_turn, tool_use, max_tokens, stop_sequence, pause_turn, refusal — branch on each.
• Retry 429/5xx/529 with backoff + jitter + retry-after; fix 400/401/403/404/413.
• max_tokens = truncation, refusal = safety decline — both need explicit handling, not silent pass-through.
• Tool failures use structured is_error, never empty success or an HTTP error.
• On repeated 529, fall back only to a newer-or-equal model to keep Fable 5.1 thinking blocks valid.