Raisons d'arrêt et erreurs

Les items de fiabilité reposent sur deux énumérations : les valeurs de stop_reason sur lesquelles une boucle doit brancher, et les erreurs HTTP qu’un client doit classer en réessai-ou-correction. Cette page couvre chacune avec cause, détection et traitement.

stop_reason — chaque valeur

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

Erreurs HTTP — chaque statut

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');
}

Erreurs de streaming

Un événement error peut arriver en cours de flux (communément overloaded_error). Traitez-le comme le statut HTTP : surcharge/timeout réessayable → backoff et redémarrez le flux ; requête malformée → corrigez.

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

Erreurs d’exécution d’outil (pas HTTP)

Un outil qui échoue n’est pas une erreur API — l’appel API a réussi. Renvoyez un tool_result structuré avec 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\"}" }

Ne renvoyez jamais un succès vide sur échec (anti-pattern de silent empty-success).

Référence rapide de décision

Idées reçues courantes

Analyse de scénario

Un agent sur Opus 5 en production, par intermittence : (a) renvoie du JSON coupé, (b) atteint des 529 sous charge, (c) a une fois renvoyé un refus de sécurité montré aux utilisateurs comme « Error 500 », et (d) un ingénieur a ajouté tool_choice: "any" après avoir basculé un flux vers Fable 5.1 et obtient maintenant des 400.

1. JSON coupé — stop_reason: max_tokens. Augmentez max_tokens et/ou continuez ; validez avant usage.
2. 529 — réessayable ; backoff exponentiel + jitter respectant retry-after ; après des 529 répétés, basculez vers un modèle plus récent ou équivalent (pas vers le bas).
3. Refus montré comme 500 — stop_reason: refusal a été mal géré ; routez vers un message de repli explicite, pas une erreur générique.
4. 400 sur Fable 5.1 — le tool_choice forcé est non supporté (400, non réessayable) ; basculez vers auto+instruction, strict: true, ou output_config.format.

Alternatives rejetées : réessayer le 400 (erreur client — corrigez-la), traiter le JSON tronqué comme valide (silent failure), et présenter le refus comme un 500 (mauvaise gestion de refus).

Points clés à retenir

• Valeurs de stop_reason : end_turn, tool_use, max_tokens, stop_sequence, pause_turn, refusal — branchez sur chacune.
• Réessayez 429/5xx/529 avec backoff + jitter + retry-after ; corrigez 400/401/403/404/413.
• max_tokens = troncature, refusal = refus de sécurité — les deux nécessitent une gestion explicite, pas un laisser-passer silencieux.
• Les échecs d’outil utilisent un is_error structuré, jamais un succès vide ni une erreur HTTP.
• Sur des 529 répétés, ne basculez que vers un modèle plus récent ou équivalent pour garder valides les blocs de thinking de Fable 5.1.