Claude Platform Docs
MessaggiSviluppare con Claude

Motivi di arresto e fallback

Scopri cosa significa ciascun valore di stop_reason e come gestire il troncamento, l’uso degli strumenti, i turni in pausa e i rifiuti nella tua applicazione.

Ogni risposta della Messages API include un campo stop_reasonAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) che ti indica perché Claude ha smesso di generare. Controlla questo campo per decidere se usare la risposta così com’è, continuare la conversazione, riprovare o ripiegare su un altro modello.

Per lo schema completo della risposta, consulta il riferimento della Messages APIAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro).

Riferimento rapido

ValoreQuando si verificaCosa fare
end_turnClaude ha completato la sua risposta in modo naturale.Usa la risposta.
max_tokensLa risposta ha raggiunto il tuo limite max_tokens.Aumenta max_tokens oppure continua la risposta.
stop_sequenceClaude ha emesso una delle tue stop_sequences.Leggi stop_sequence per vedere quale si è attivata.
tool_useClaude sta chiamando uno strumento.Esegui lo strumento e restituisci il risultato. Una chiamata a uno strumento server a cui manca ancora il blocco di risultato viene completata in una risposta successiva.
pause_turnUn ciclo di strumenti server ha raggiunto il suo limite di iterazioni.Rimanda indietro il contenuto dell’assistente per continuare.
refusalClaude ha rifiutato di rispondere.Leggi stop_details e riprova su un modello di fallback.
model_context_window_exceededLa risposta ha riempito la finestra di contesto del modello.Tratta la risposta come troncata.

Il campo stop_reason

Il campo stop_reason fa parte di ogni risposta riuscita della Messages API. A differenza degli errori, che indicano fallimenti nell’elaborazione della tua richiesta, stop_reason ti indica perché Claude ha completato la generazione della sua risposta.

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
  }
}

Valori del motivo di arresto

end_turn

Il motivo di arresto più comune. Indica che Claude ha completato la sua risposta in modo naturale.

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":
    # Elabora la risposta completa
    for block in response.content:
        if block.type == "text":
            print(block.text)

max_tokens

Claude si è fermato perché ha raggiunto il limite max_tokensAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) specificato nella tua richiesta.

client = anthropic.Anthropic()
# Richiesta con token limitati
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":
    # La risposta è stata troncata
    print("Response was cut off at token limit")
    # Valuta di effettuare un'altra richiesta per continuare

stop_sequence

Claude ha incontrato una delle tue sequenze di arrestoAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) personalizzate.

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 sta chiamando uno strumento che devi eseguire.

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":
    # Estrai ed esegui lo strumento
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            # Restituisci il risultato a Claude per la risposta finale

Quando uno strumento server è ancora in attesa

Claude può chiamare uno strumento server e uno strumento client (uno strumento eseguito dal tuo codice) nello stesso gruppo di chiamate parallele agli strumenti. L’API restituisce quindi una risposta tool_use senza eseguire lo strumento server, così che tu possa eseguire prima gli strumenti client.

La chiamata in attesa è un blocco server_tool_use o mcp_tool_use senza blocco di risultato. Nient’altro nella risposta la contrassegna. Dopo l’esecuzione di uno strumento server, il suo blocco di risultato, come web_search_tool_result, contiene l’id della chiamata nel suo campo tool_use_id.

Questa risposta mista contiene uno strumento server in attesa e una chiamata a uno strumento client:

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" }
    }
  ]
}

Per continuare da una risposta mista come questa, costruisci una richiesta successiva:

  1. Mantieni i messaggi precedenti e aggiungi il content della risposta senza modifiche come messaggio assistant.
  2. Aggiungi un messaggio utente che contenga solo blocchi tool_result, uno per ogni blocco client tool_use. Una chiamata in attesa non ne riceve nessuno.
  3. Invia la richiesta con lo stesso array tools di prima, così che lo strumento server in attesa sia ancora definito.

Per i campi di un blocco tool_result, vedi Gestire le chiamate agli strumenti. Il messaggio utente nella richiesta successiva ha questo aspetto:

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"
    }
  ]
}

L’API aggiunge i tuoi risultati al turno non terminato di Claude, esegue lo strumento server in attesa e continua. Per uno strumento server chiamato direttamente da Claude, il content della risposta successiva inizia con il blocco di risultato di quello strumento.

Un ciclo che segue i passaggi precedenti per ogni risposta tool_use non ha bisogno di rilevare uno strumento server in attesa. Nelle richieste successive, mantieni tre messaggi separati in messages, in questo ordine: la prima risposta, il tuo messaggio tool_result e la risposta successiva.

Due casi richiedono un campo in più nella richiesta successiva:

  • La risposta include un container: Rinvia il suo ID (vedi la sezione Riutilizzo del container dello strumento di esecuzione del codice).
  • Il blocco in attesa è un blocco mcp_tool_use: Invia gli stessi mcp_servers di prima.

Ciascuno di questi errori nella richiesta successiva fallisce con un 400 invalid_request_error. I messaggi mostrati si riferiscono alla ricerca web. Per altri strumenti server, i nomi al loro interno sono diversi.

ErroreIl messaggio di errore include
tools non definisce più lo strumento server in attesabut no `web_search` tool was provided
Testo o altro contenuto segue i blocchi tool_resultwas found without a corresponding `web_search_tool_result` block
Con la chiamata programmatica degli strumenti, testo o altro contenuto segue i blocchi tool_resultonly tool_result blocks are allowed
Testo o altro contenuto precede i blocchi tool_result`tool_use` ids were found without `tool_result` blocks immediately after
Manca un blocco tool_result`tool_use` ids were found without `tool_result` blocks immediately after

Il contenuto dopo i blocchi tool_result fallisce perché termina il turno di Claude mentre lo strumento server è ancora in attesa. Per fornire a Claude ulteriore input, continua finché lo stop_reason di una risposta non è né tool_use né pause_turn. Quindi, invia l’input come nuovo messaggio utente nella stessa lista messages.

pause_turn

Restituito quando il ciclo di campionamento lato server raggiunge il suo limite di iterazioni durante l’esecuzione di strumenti server come la ricerca web. Il limite predefinito è di 10 iterazioni per ogni richiesta.

Quando Claude si ferma per chiamare uno strumento che esegui tu, il motivo di arresto è tool_use, mai pause_turn.

Per consentire a Claude di completare un turno in pausa, costruisci una nuova richiesta:

  1. Mantieni i messaggi precedenti e aggiungi il content della risposta senza modifiche come messaggio assistant, incluso qualsiasi blocco server_tool_use che non ha un blocco di risultato.
  2. Invia la richiesta con gli stessi tools di prima e nessun messaggio utente dopo il messaggio assistant.

Se la risposta include un container, rinvia anche il suo ID così che il turno mantenga i suoi file. Per i dettagli, vedi la sezione Riutilizzo del container dello strumento di esecuzione del codice. Gli esempi seguenti usano la ricerca web e non inviano alcun ID del container:

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":
    # Continua la conversazione inviando di nuovo la risposta
    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"}],
    )

La tua applicazione dovrebbe gestire pause_turn in qualsiasi ciclo agente che usa strumenti server. Per un ciclo che gestisce pause ripetute e rinvia l’ID del container, vedi Implementa la logica di nuovo tentativo per pause_turn.

refusal

Claude ha rifiutato di generare una risposta. I classificatori di sicurezza restituiscono questo motivo di arresto come una normale risposta HTTP 200, non come un errore.

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 si è rifiutato di rispondere
    print("Claude was unable to process this request")
    # Valuta di riformulare o modificare la richiesta

In caso di rifiuto, l’oggetto stop_detailsAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) identifica la categoria di policy che lo ha attivato. Le categorie e la forma completa della risposta di rifiuto sono trattate in Come appare un rifiuto. stop_details è null per tutti i motivi di arresto diversi da refusal.

Di solito puoi ottenere una risposta a una richiesta rifiutata riprovandola su un altro modello Claude. Questo funziona per Claude Fable 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 e Claude Haiku 5.5. Rifiuti e fallback mostra come configurare quel nuovo tentativo, lato server o nel tuo client. Claude Haiku 5.5 non ha un fallback lato server, quindi configura il suo nuovo tentativo con il fallback lato client. Se costruisci tu stesso il nuovo tentativo a partire da uno qualsiasi di questi modelli tranne Claude Haiku 5.5, Credito di fallback spiega come evitare di pagare due volte il costo della cache dei prompt.

model_context_window_exceeded

Claude si è fermato perché ha raggiunto il limite della “context window” (finestra di contesto) del modello. Questo ti consente di richiedere il massimo numero possibile di token senza conoscere la dimensione esatta dell’input.

client = anthropic.Anthropic()

# Richiesta con il numero massimo di token per ottenere il più possibile
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":
    # La risposta ha raggiunto il limite della finestra di contesto prima di max_tokens
    print("Response reached model's context window limit")
    # La risposta è comunque valida, ma è stata limitata dalla finestra di contesto

Best practice per la gestione dei motivi di arresto

Controlla sempre stop_reason

Prendi l’abitudine di controllare lo stop_reason nella tua logica di gestione delle risposte:

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 _:
            # Gestisci end_turn e gli altri casi
            return next(
                (block.text for block in response.content if block.type == "text"),
                "",
            )

Gestisci le risposte troncate in modo appropriato

Quando una risposta viene troncata a causa dei limiti di token o della finestra di contesto, aggiungi un avviso in modo che il lettore sappia che l’output è incompleto. Per continuare invece a generare dal punto in cui la risposta si è interrotta, consulta Garantire risposte complete.

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

Implementa la logica di nuovo tentativo per pause_turn

Quando usi gli strumenti server, l’API potrebbe restituire pause_turn se il ciclo di campionamento lato server raggiunge il suo limite di iterazioni (predefinito 10). Gestiscilo aggiungendo la risposta in pausa ai tuoi messaggi senza modificarla e inviando di nuovo la richiesta. Se la risposta include un container, rinvia anche il suo ID. Senza di esso, la richiesta successiva avvia un nuovo container e i file creati in precedenza nel turno vanno persi.

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":
            # Non in pausa: restituisci la risposta
            return response

        # pause_turn: aggiungi la risposta in pausa come messaggio dell'assistente, poi continua
        messages.append({"role": "assistant", "content": response.content})

        # Se gli strumenti sono stati eseguiti in un container, rinvia il suo ID per conservarne i file
        if response.container:
            container_id = response.container.id

    # Ancora in pausa dopo max_requests richieste: restituisci l'ultima risposta
    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)

La funzione restituisce l’ultima risposta, che contiene solo la parte finale del turno. Per mostrare l’intero turno o per continuare la conversazione, conserva anche le risposte in pausa.

Motivi di arresto e errori a confronto

È importante distinguere tra i valori di stop_reason e gli errori veri e propri:

Motivi di arresto (risposte riuscite)

  • Fanno parte del corpo della risposta
  • Indicano perché la generazione si è fermata normalmente
  • La risposta contiene contenuto valido

Errori (richieste fallite)

  • Codici di stato HTTP 4xx o 5xx
  • Indicano fallimenti nell’elaborazione della richiesta
  • La risposta contiene i dettagli dell’errore
client = anthropic.Anthropic()

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

    # Gestisci la risposta riuscita con stop_reason
    if response.stop_reason == "max_tokens":
        print("Response was truncated")

except anthropic.APIStatusError as e:
    # Gestisci gli errori effettivi
    match e.status_code:
        case 429:
            print("Rate limit exceeded")
        case 500:
            print("Server error")

Considerazioni sullo streaming

Quando usi lo streaming, stop_reason è:

  • null nell’evento iniziale message_start
  • Fornito nell’evento message_delta
  • Non fornito in nessun altro evento
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}")

Pattern comuni

Gestione dei flussi di lavoro con uso degli strumenti

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":
            # Esegui gli strumenti e continua
            tool_results = execute_tools(response.content)
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})
        else:
            # Risposta finale
            return response

Garantire risposte complete

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

        # Riprendi da dove si era interrotto
        messages = [
            {"role": "user", "content": prompt},
            {"role": "assistant", "content": full_response},
            {"role": "user", "content": "Please continue from where you left off."},
        ]

    return full_response

Ottenere il massimo numero di token senza conoscere la dimensione dell’input

Con il motivo di arresto model_context_window_exceeded, puoi richiedere il massimo numero possibile di token senza calcolare la dimensione dell’input:

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":
            # Ottenuto il numero massimo di token possibile data la dimensione dell'input
            print(
                f"Generated {response.usage.output_tokens} tokens (context limit reached)"
            )
        case "max_tokens":
            # Ottenuto esattamente il numero di token richiesto
            print(
                f"Generated {response.usage.output_tokens} tokens (max_tokens reached)"
            )
        case _:
            # Completamento naturale
            print(
                f"Generated {response.usage.output_tokens} tokens (natural completion)"
            )

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

Prossimi passi

Riprova le richieste rifiutate su un modello di fallback, lato server o nel tuo client.

Lascia che l’SDK gestisca per te il ciclo tool_use, la formattazione dei risultati e i nuovi tentativi.

Leggi stop_reason dall’evento message_delta durante lo streaming.

Gestisci gli errori HTTP 4xx e 5xx, che sono distinti dai motivi di arresto.

Questa pagina ti è stata utile?