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
| Valore | Quando si verifica | Cosa fare |
|---|---|---|
end_turn | Claude ha completato la sua risposta in modo naturale. | Usa la risposta. |
max_tokens | La risposta ha raggiunto il tuo limite max_tokens. | Aumenta max_tokens oppure continua la risposta. |
stop_sequence | Claude ha emesso una delle tue stop_sequences. | Leggi stop_sequence per vedere quale si è attivata. |
tool_use | Claude 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_turn | Un ciclo di strumenti server ha raggiunto il suo limite di iterazioni. | Rimanda indietro il contenuto dell’assistente per continuare. |
refusal | Claude ha rifiutato di rispondere. | Leggi stop_details e riprova su un modello di fallback. |
model_context_window_exceeded | La 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.
{
"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)A volte Claude restituisce una risposta vuota (esattamente 2–3 token senza contenuto) con stop_reason: "end_turn". Questo si verifica tipicamente quando Claude determina che il turno dell’assistente è completo, in particolare dopo i risultati degli strumenti.
Cause comuni:
- Aggiungere blocchi di testo immediatamente dopo i risultati degli strumenti (la cronologia mostra quindi testo dell’utente dopo ogni risultato di strumento, quindi Claude termina il suo turno per seguire quello schema)
- Rimandare indietro la risposta completata di Claude senza aggiungere nulla (Claude ha già stabilito di aver finito, quindi rimarrà tale)
Come prevenire le risposte vuote:
# ERRATO: aggiunta di testo subito dopo tool_result
messages = [
{"role": "user", "content": "Calculate the sum of 1234 and 5678"},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_123",
"name": "calculator",
"input": {"operation": "add", "a": 1234, "b": 5678},
}
],
},
{
"role": "user",
"content": [
{"type": "tool_result", "tool_use_id": "toolu_123", "content": "6912"},
{
"type": "text",
"text": "Here's the result", # Don't add text after tool_result
},
],
},
]
# CORRETTO: invia i risultati degli strumenti direttamente senza testo aggiuntivo
messages = [
{"role": "user", "content": "Calculate the sum of 1234 and 5678"},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_123",
"name": "calculator",
"input": {"operation": "add", "a": 1234, "b": 5678},
}
],
},
{
"role": "user",
"content": [
{"type": "tool_result", "tool_use_id": "toolu_123", "content": "6912"}
],
}, # Only the tool_result, no additional text
]Se ottieni ancora risposte vuote dopo aver corretto la struttura dei messaggi, aggiungi un prompt di continuazione in un nuovo messaggio utente invece di riprovare con la risposta vuota:
def handle_empty_response(client, messages):
response = client.messages.create(
model="claude-opus-5-5", max_tokens=1024, messages=messages
)
# Verifica se la risposta è vuota
if response.stop_reason == "end_turn" and not response.content:
# ERRATO: non limitarti a riprovare con la risposta vuota
# Non funzionerà perché Claude ha già deciso di aver finito
# CORRETTO: aggiungi un prompt di continuazione in un NUOVO messaggio utente
messages.append({"role": "user", "content": "Please continue"})
response = client.messages.create(
model="claude-opus-5-5", max_tokens=1024, messages=messages
)
return responseBest practice:
- Non aggiungere mai blocchi di testo immediatamente dopo i risultati degli strumenti: Questo stabilisce uno schema di input dell’utente dopo ogni uso di uno strumento, e Claude segue quello schema terminando il suo turno.
- Non riprovare le risposte vuote senza modifiche: Rimandare indietro la risposta vuota non aiuterà.
- Usa i prompt di continuazione come ultima risorsa: Solo se queste correzioni non risolvono il problema.
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 continuareSe la risposta di Claude viene interrotta perché ha raggiunto il limite max_tokens, e la risposta troncata contiene un blocco di uso degli strumenti incompleto, dovrai riprovare la richiesta con un valore max_tokens più alto per ottenere l’uso degli strumenti completo.
# Verifica se la risposta è stata troncata durante l'uso degli strumenti
if response.stop_reason == "max_tokens":
# Verifica se l'ultimo blocco di contenuto è un tool_use incompleto
last_block = response.content[-1]
if last_block.type == "tool_use":
# Invia la richiesta con un valore di max_tokens più alto
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096, # Increased limit
messages=messages,
tools=tools,
)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 finaleQuando 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:
{
"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:
- Mantieni i messaggi precedenti e aggiungi il
contentdella risposta senza modifiche come messaggioassistant. - Aggiungi un messaggio utente che contenga solo blocchi
tool_result, uno per ogni blocco clienttool_use. Una chiamata in attesa non ne riceve nessuno. - Invia la richiesta con lo stesso array
toolsdi 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:
{
"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 stessimcp_serversdi 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.
| Errore | Il messaggio di errore include |
|---|---|
tools non definisce più lo strumento server in attesa | but no `web_search` tool was provided |
Testo o altro contenuto segue i blocchi tool_result | was found without a corresponding `web_search_tool_result` block |
Con la chiamata programmatica degli strumenti, testo o altro contenuto segue i blocchi tool_result | only 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:
- Mantieni i messaggi precedenti e aggiungi il
contentdella risposta senza modifiche come messaggioassistant, incluso qualsiasi bloccoserver_tool_useche non ha un blocco di risultato. - Invia la richiesta con gli stessi
toolsdi prima e nessun messaggio utente dopo il messaggioassistant.
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 richiestaIn 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 contestoBest 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 textImplementa 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 è:
nullnell’evento inizialemessage_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 responseGarantire 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_responseOttenere 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?