Claude Platform Docs
MessagesEntwickeln mit Claude

Stop-Gründe und Fallback

Erfahre, was jeder stop_reason-Wert bedeutet und wie du Abschneidung, Tool-Nutzung, pausierte Turns und Ablehnungen in deiner Anwendung behandelst.

Jede Antwort der Messages API enthält ein Feld stop_reasonVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren., das dir mitteilt, warum Claude die Generierung beendet hat. Prüfe dieses Feld, um zu entscheiden, ob du die Antwort unverändert verwendest, die Konversation fortsetzt, es erneut versuchst oder auf ein anderes Modell zurückfällst.

Das vollständige Antwortschema findest du in der Messages-API-ReferenzVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..

Kurzübersicht

WertWann er auftrittWas zu tun ist
end_turnClaude hat seine Antwort auf natürliche Weise abgeschlossen.Verwende die Antwort.
max_tokensDie Antwort hat dein max_tokens-Limit erreicht.Erhöhe max_tokens oder setze die Antwort fort.
stop_sequenceClaude hat eine deiner stop_sequences ausgegeben.Lies stop_sequence, um zu sehen, welche ausgelöst wurde.
tool_useClaude ruft ein Tool auf.Führe das Tool aus und gib das Ergebnis zurück. Ein Server-Tool-Aufruf, dem sein Ergebnisblock noch fehlt, wird in einer späteren Antwort abgeschlossen.
pause_turnEine Server-Tool-Schleife hat ihr Iterationslimit erreicht.Sende den Assistant-Inhalt zurück, um fortzufahren.
refusalClaude hat eine Antwort abgelehnt.Lies stop_details und versuche es erneut mit einem Fallback-Modell.
model_context_window_exceededDie Antwort hat das Kontextfenster des Modells gefüllt.Behandle die Antwort als abgeschnitten.

Das Feld stop_reason

Das Feld stop_reason ist Teil jeder erfolgreichen Antwort der Messages API. Anders als Fehler, die auf Probleme bei der Verarbeitung deiner Anfrage hinweisen, teilt dir stop_reason mit, warum Claude die Generierung seiner Antwort abgeschlossen hat.

Example response
{
  "id": "msg_01234",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here's the answer to your question..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "stop_details": null,
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50
  }
}

Werte von stop_reason

end_turn

Der häufigste „stop reason“ (Stoppgrund). Zeigt an, dass Claude seine Antwort auf natürliche Weise abgeschlossen hat.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
if response.stop_reason == "end_turn":
    # Verarbeite die vollständige Antwort
    for block in response.content:
        if block.type == "text":
            print(block.text)

max_tokens

Claude hat gestoppt, weil es das in deiner Anfrage angegebene max_tokensVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.-Limit erreicht hat.

client = anthropic.Anthropic()
# Anfrage mit begrenzten Tokens
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=10,
    messages=[{"role": "user", "content": "Explain quantum physics"}],
)

if response.stop_reason == "max_tokens":
    # Antwort wurde abgeschnitten
    print("Response was cut off at token limit")
    # Erwäge eine weitere Anfrage, um fortzufahren

stop_sequence

Claude ist auf eine deiner benutzerdefinierten Stop-SequenzenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. gestoßen.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    stop_sequences=["END", "STOP"],
    messages=[{"role": "user", "content": "Generate text until you say END"}],
)

if response.stop_reason == "stop_sequence":
    print(f"Stopped at sequence: {response.stop_sequence}")

tool_use

Claude ruft ein Tool auf, das du ausführen musst.

client = anthropic.Anthropic()
weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "City and state"},
        },
        "required": ["location"],
    },
}


def execute_tool(name, tool_input):
    """Run a tool and return the result."""
    return f"Weather in {tool_input.get('location', 'unknown')}: 72°F"


response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
)

if response.stop_reason == "tool_use":
    # Extrahiere das Tool und führe es aus
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            # Gib das Ergebnis für die finale Antwort an Claude zurück

Wenn ein Server-Tool noch wartet

Claude kann ein Server-Tool und ein Client-Tool (ein Tool, das dein Code ausführt) in derselben Gruppe paralleler Tool-Aufrufe aufrufen. Die API gibt dann eine tool_use-Antwort zurück, ohne das Server-Tool auszuführen, damit du zuerst die Client-Tools ausführen kannst.

Der wartende Aufruf ist ein server_tool_use- oder mcp_tool_use-Block ohne Ergebnisblock. Nichts anderes in der Antwort markiert ihn. Nachdem ein Server-Tool ausgeführt wurde, enthält sein Ergebnisblock, etwa web_search_tool_result, die id des Aufrufs in seinem tool_use_id-Feld.

Diese gemischte Antwort enthält ein wartendes Server-Tool und einen Client-Tool-Aufruf:

A mixed tool_use response
{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "name": "web_search",
      "input": { "query": "example article" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "name": "run_command",
      "input": { "command": "uname -a" }
    }
  ]
}

Um ausgehend von einer gemischten Antwort wie dieser fortzufahren, erstelle eine Folgeanfrage:

  1. Behalte die früheren Nachrichten bei und füge den content der Antwort unverändert als assistant-Nachricht hinzu.
  2. Füge eine User-Nachricht hinzu, die nur tool_result-Blöcke enthält, einen für jeden Client-tool_use-Block. Ein wartender Aufruf erhält keinen.
  3. Sende die Anfrage mit demselben tools-Array wie zuvor, damit das wartende Server-Tool weiterhin definiert ist.

Die Felder eines tool_result-Blocks findest du unter Tool-Aufrufe behandeln. Die User-Nachricht in der Folgeanfrage sieht so aus:

The follow-up user message
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
    }
  ]
}

Die API fügt deine Ergebnisse an Claudes unvollendeten Turn an, führt das wartende Server-Tool aus und fährt fort. Bei einem Server-Tool, das Claude direkt aufgerufen hat, beginnt der content der nächsten Antwort mit dem Ergebnisblock dieses Tools.

Eine Schleife, die die vorstehenden Schritte für jede tool_use-Antwort befolgt, muss ein wartendes Server-Tool nicht erkennen. Behalte bei späteren Anfragen drei separate Nachrichten in messages, in dieser Reihenfolge: die erste Antwort, deine tool_result-Nachricht und die nächste Antwort.

Zwei Fälle erfordern ein weiteres Feld in der Folgeanfrage:

  • Die Antwort enthält einen container: Sende dessen ID zurück (siehe den Abschnitt Container-Wiederverwendung des Code-Execution-Tools).
  • Der wartende Block ist ein mcp_tool_use-Block: Sende dieselben mcp_servers wie zuvor.

Jeder dieser Fehler in der Folgeanfrage schlägt mit einem 400 invalid_request_error fehl. Die gezeigten Meldungen gelten für die Websuche. Bei anderen Server-Tools unterscheiden sich die Namen darin.

FehlerDie Fehlermeldung enthält
tools definiert das wartende Server-Tool nicht mehrbut no `web_search` tool was provided
Text oder anderer Inhalt folgt nach den tool_result-Blöckenwas found without a corresponding `web_search_tool_result` block
Beim programmatischen Tool-Aufruf folgt Text oder anderer Inhalt nach den tool_result-Blöckenonly tool_result blocks are allowed
Text oder anderer Inhalt steht vor den tool_result-Blöcken`tool_use` ids were found without `tool_result` blocks immediately after
Ein tool_result-Block fehlt`tool_use` ids were found without `tool_result` blocks immediately after

Inhalt nach den tool_result-Blöcken schlägt fehl, weil er Claudes Turn beendet, während das Server-Tool noch wartet. Um Claude weitere Eingaben zu geben, fahre fort, bis der stop_reason einer Antwort weder tool_use noch pause_turn ist. Sende die Eingabe dann als neue User-Nachricht in derselben messages-Liste.

pause_turn

Wird zurückgegeben, wenn die serverseitige Sampling-Schleife beim Ausführen von Server-Tools wie der Websuche ihr Iterationslimit erreicht. Das Standardlimit beträgt 10 Iterationen pro Anfrage.

Wenn Claude anhält, um ein Tool aufzurufen, das du ausführst, ist der Stop-Grund tool_use, niemals pause_turn.

Damit Claude einen pausierten Turn abschließen kann, erstelle eine neue Anfrage:

  1. Behalte die früheren Nachrichten bei und füge den content der Antwort unverändert als assistant-Nachricht hinzu, einschließlich aller server_tool_use-Blöcke ohne Ergebnisblock.
  2. Sende die Anfrage mit denselben tools wie zuvor und ohne User-Nachricht nach der assistant-Nachricht.

Wenn die Antwort einen container enthält, sende auch dessen ID zurück, damit der Turn seine Dateien behält. Details findest du im Abschnitt Container-Wiederverwendung des Code-Execution-Tools. Die folgenden Beispiele verwenden die Websuche und senden keine Container-ID:

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    messages=[{"role": "user", "content": "Search for latest AI news"}],
)

if response.stop_reason == "pause_turn":
    # Setze die Unterhaltung fort, indem du die Antwort zurücksendest
    messages = [
        {"role": "user", "content": "Search for latest AI news"},
        {"role": "assistant", "content": response.content},
    ]
    continuation = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search"}],
    )

Deine Anwendung sollte pause_turn in jeder Agentenschleife behandeln, die Server-Tools verwendet. Eine Schleife, die wiederholte Pausen behandelt und die Container-ID zurücksendet, findest du unter Implementiere Retry-Logik für pause_turn.

refusal

Claude hat es abgelehnt, eine Antwort zu generieren. Sicherheitsklassifikatoren geben diesen Stop-Grund als normale HTTP-200-Antwort zurück, nicht als Fehler.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "[Unsafe request]"}],
)

if response.stop_reason == "refusal":
    # Claude hat eine Antwort abgelehnt
    print("Claude was unable to process this request")
    # Formuliere die Anfrage ggf. um oder passe sie an

Bei einer Ablehnung identifiziert das stop_detailsVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.-Objekt die Richtlinienkategorie, die sie ausgelöst hat. Die Kategorien und die vollständige Form der Ablehnungsantwort werden unter Wie eine Ablehnung aussieht behandelt. stop_details ist für alle Stoppgründe außer refusal gleich null.

Eine Antwort auf eine abgelehnte Anfrage kannst du in der Regel erhalten, indem du sie mit einem anderen Claude-Modell erneut versuchst. Das funktioniert für Claude Fable 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 und Claude Haiku 5.5. Ablehnungen und Fallback zeigt, wie du diesen erneuten Versuch einrichtest, serverseitig oder in deinem Client. Claude Haiku 5.5 hat keinen serverseitigen Fallback, richte den erneuten Versuch daher mit clientseitigem Fallback ein. Wenn du den erneuten Versuch von einem dieser Modelle außer Claude Haiku 5.5 aus selbst aufbaust, erklärt Fallback-Gutschrift, wie du vermeidest, die Prompt-Cache-Kosten doppelt zu bezahlen.

model_context_window_exceeded

Claude hat gestoppt, weil es das Limit des „context window“ (Kontextfenster) des Modells erreicht hat. Dadurch kannst du die maximal möglichen Token anfordern, ohne die genaue Eingabegröße zu kennen.

client = anthropic.Anthropic()

# Anfrage mit maximaler Token-Anzahl, um so viel wie möglich zu erhalten
response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k
    messages=[
        {"role": "user", "content": "Large input that uses most of context window..."}
    ],
)

if response.stop_reason == "model_context_window_exceeded":
    # Antwort hat das Limit des Kontextfensters vor max_tokens erreicht
    print("Response reached model's context window limit")
    # Die Antwort ist weiterhin gültig, wurde aber durch das Kontextfenster begrenzt

Best Practices für den Umgang mit Stop-Gründen

Prüfe immer stop_reason

Mache es dir zur Gewohnheit, den stop_reason in deiner Antwortverarbeitungslogik zu prüfen:

def handle_response(response):
    match response.stop_reason:
        case "tool_use":
            return handle_tool_use(response)
        case "max_tokens":
            return handle_truncation(response)
        case "model_context_window_exceeded":
            return handle_context_limit(response)
        case "pause_turn":
            return handle_pause(response)
        case "refusal":
            return handle_refusal(response)
        case _:
            # Behandle end_turn und andere Fälle
            return next(
                (block.text for block in response.content if block.type == "text"),
                "",
            )

Behandle abgeschnittene Antworten elegant

Wenn eine Antwort aufgrund von Token-Limits oder des Kontextfensters abgeschnitten wird, hänge einen Hinweis an, damit der Leser weiß, dass die Ausgabe unvollständig ist. Um stattdessen die Generierung dort fortzusetzen, wo die Antwort aufgehört hat, siehe Vollständige Antworten sicherstellen.

def handle_truncated_response(response):
    text = next((block.text for block in response.content if block.type == "text"), "")
    if response.stop_reason in ["max_tokens", "model_context_window_exceeded"]:
        if response.stop_reason == "max_tokens":
            note = "[Response truncated due to max_tokens limit]"
        else:
            note = "[Response truncated due to context window limit]"
        return f"{text}\n\n{note}"
    return text

Implementiere Retry-Logik für pause_turn

Wenn du Server-Tools verwendest, kann die API pause_turn zurückgeben, wenn die serverseitige Sampling-Schleife ihr Iterationslimit erreicht (Standard 10). Behandle dies, indem du die pausierte Antwort unverändert zu deinen Nachrichten hinzufügst und die Anfrage erneut sendest. Wenn die Antwort einen container enthält, sende auch dessen ID zurück. Ohne sie startet die nächste Anfrage einen neuen Container, und Dateien aus dem früheren Verlauf des Turns gehen verloren.

client = anthropic.Anthropic()


def handle_server_tool_conversation(client, user_query, tools, max_requests=5):
    messages = [{"role": "user", "content": user_query}]
    container_id = None

    for _ in range(max_requests):
        response = client.messages.create(
            model="claude-opus-5-5",
            max_tokens=4096,
            messages=messages,
            tools=tools,
            container=container_id,
        )

        if response.stop_reason != "pause_turn":
            # Nicht pausiert: gib die Antwort zurück
            return response

        # pause_turn: füge die pausierte Antwort als Assistant-Nachricht hinzu und fahre dann fort
        messages.append({"role": "assistant", "content": response.content})

        # Wenn die Tools in einem Container liefen, sende dessen ID zurück, damit seine Dateien erhalten bleiben
        if response.container:
            container_id = response.container.id

    # Nach max_requests Anfragen immer noch pausiert: gib die letzte Antwort zurück
    return response


response = handle_server_tool_conversation(
    client,
    "Use the code execution tool to find the 1,000th prime number.",
    [{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response.stop_reason)

Die Funktion gibt die letzte Antwort zurück, die nur den letzten Teil des Turns enthält. Um den gesamten Turn anzuzeigen oder die Konversation fortzusetzen, behalte auch die pausierten Antworten.

Stoppgründe versus Fehler

Es ist wichtig, zwischen stop_reason-Werten und tatsächlichen Fehlern zu unterscheiden:

Stop-Gründe (erfolgreiche Antworten)

  • Teil des Antwort-Bodys
  • Zeigen an, warum die Generierung normal gestoppt hat
  • Antwort enthält gültigen Inhalt

Fehler (fehlgeschlagene Anfragen)

  • HTTP-Statuscodes 4xx oder 5xx
  • Zeigen Fehler bei der Anfrageverarbeitung an
  • Antwort enthält Fehlerdetails
client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello!"}],
    )

    # Erfolgreiche Antwort mit stop_reason verarbeiten
    if response.stop_reason == "max_tokens":
        print("Response was truncated")

except anthropic.APIStatusError as e:
    # Tatsächliche Fehler behandeln
    match e.status_code:
        case 429:
            print("Rate limit exceeded")
        case 500:
            print("Server error")

Überlegungen zum Streaming

Bei der Verwendung von Streaming ist stop_reason:

  • null im initialen message_start-Event
  • Im message_delta-Event enthalten
  • In keinem anderen Event enthalten
client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
) as stream:
    for event in stream:
        if event.type == "message_delta":
            stop_reason = event.delta.stop_reason
            if stop_reason:
                print(f"Stream ended with: {stop_reason}")

Häufige Muster

Umgang mit Tool-Nutzungs-Workflows

def complete_tool_workflow(client, user_query, tools):
    messages = [{"role": "user", "content": user_query}]

    while True:
        response = client.messages.create(
            model="claude-opus-5-5",
            max_tokens=1024,
            messages=messages,
            tools=tools,
        )

        if response.stop_reason == "tool_use":
            # Tools ausführen und fortfahren
            tool_results = execute_tools(response.content)
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})
        else:
            # Endgültige Antwort
            return response

Vollständige Antworten sicherstellen

def get_complete_response(client, prompt, max_attempts=3):
    messages = [{"role": "user", "content": prompt}]
    full_response = ""

    for _ in range(max_attempts):
        response = client.messages.create(
            model="claude-opus-5-5", messages=messages, max_tokens=4096
        )

        full_response += next(
            (block.text for block in response.content if block.type == "text"), ""
        )

        if response.stop_reason != "max_tokens":
            break

        # Mach dort weiter, wo es aufgehört hat
        messages = [
            {"role": "user", "content": prompt},
            {"role": "assistant", "content": full_response},
            {"role": "user", "content": "Please continue from where you left off."},
        ]

    return full_response

Maximale Token erhalten, ohne die Eingabegröße zu kennen

Mit dem Stop-Grund model_context_window_exceeded kannst du die maximal möglichen Token anfordern, ohne die Eingabegröße zu berechnen:

def get_max_possible_tokens(client, prompt):
    """
    Get as many tokens as possible within the model's context window
    without needing to calculate input token count
    """
    response = client.beta.messages.create(
        model="claude-opus-5-5",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k
    )

    match response.stop_reason:
        case "model_context_window_exceeded":
            # Maximal mögliche Anzahl an Tokens für die Eingabegröße erhalten
            print(
                f"Generated {response.usage.output_tokens} tokens (context limit reached)"
            )
        case "max_tokens":
            # Genau die angeforderte Anzahl an Tokens erhalten
            print(
                f"Generated {response.usage.output_tokens} tokens (max_tokens reached)"
            )
        case _:
            # Natürlicher Abschluss
            print(
                f"Generated {response.usage.output_tokens} tokens (natural completion)"
            )

    return next((block.text for block in response.content if block.type == "text"), "")

Nächste Schritte

Versuche abgelehnte Anfragen auf einem Fallback-Modell erneut, serverseitig oder in deinem Client.

Lass das SDK die tool_use-Schleife, die Ergebnisformatierung und erneute Versuche für dich verwalten.

Lies stop_reason beim Streaming aus dem message_delta-Event.

Behandle 4xx- und 5xx-HTTP-Fehler, die sich von Stop-Gründen unterscheiden.

War diese Seite hilfreich?