Причины остановки и резервные модели
Узнайте, что означает каждое значение stop_reason и как обрабатывать усечение ответов, использование инструментов, приостановленные ходы и отказы в вашем приложении.
Каждый ответ Messages API содержит поле stop_reasonДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape., которое сообщает, почему Claude прекратил генерацию. Проверяйте это поле, чтобы решить, что делать дальше: использовать ответ как есть, продолжить разговор, повторить запрос или выполнить «fallback» (переключение на резервную модель).
Полную схему ответа см. в справочнике по Messages APIДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..
Краткий справочник
| Значение | Когда возникает | Что делать |
|---|---|---|
end_turn | Claude естественным образом завершил свой ответ. | Используйте ответ. |
max_tokens | Ответ достиг заданного вами лимита max_tokens. | Увеличьте max_tokens или продолжите ответ. |
stop_sequence | Claude выдал одну из ваших stop_sequences. | Прочитайте stop_sequence, чтобы узнать, какая из них сработала. |
tool_use | Claude вызывает инструмент. | Выполните инструмент и верните результат. Вызов серверного инструмента, для которого ещё нет блока результата, завершается в одном из последующих ответов. |
pause_turn | Цикл серверных инструментов достиг лимита итераций. | Отправьте содержимое ассистента обратно, чтобы продолжить. |
refusal | Claude отказался отвечать. | Прочитайте stop_details и повторите запрос на резервной модели. |
model_context_window_exceeded | Ответ заполнил «context window» (контекстное окно) модели. | Считайте ответ усечённым. |
Поле stop_reason
Поле stop_reason входит в каждый успешный ответ Messages API. В отличие от ошибок, которые указывают на сбои при обработке вашего запроса, stop_reason сообщает, почему Claude завершил генерацию ответа.
{
"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
}
}Значения причин остановки
end_turn
Самая распространённая «stop reason» (причина остановки). Указывает, что Claude естественным образом завершил свой ответ.
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":
# Обработать полный ответ
for block in response.content:
if block.type == "text":
print(block.text)Иногда Claude возвращает пустой ответ (ровно 2–3 токена без содержимого) с stop_reason: "end_turn". Обычно это происходит, когда Claude решает, что ход ассистента завершён, особенно после результатов инструментов.
Распространённые причины:
- Добавление текстовых блоков сразу после результатов инструментов (тогда история показывает пользовательский текст после каждого результата инструмента, и Claude завершает свой ход, следуя этому шаблону)
- Отправка завершённого ответа Claude обратно без каких-либо добавлений (Claude уже определил, что закончил, поэтому так и останется)
Как предотвратить пустые ответы:
# НЕПРАВИЛЬНО: добавление текста сразу после 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
},
],
},
]
# ПРАВИЛЬНО: отправляйте результаты инструментов напрямую, без дополнительного текста
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
]Если после исправления структуры сообщений вы всё ещё получаете пустые ответы, добавьте подсказку для продолжения в новом пользовательском сообщении, а не повторяйте запрос с пустым ответом:
def handle_empty_response(client, messages):
response = client.messages.create(
model="claude-opus-5-5", max_tokens=1024, messages=messages
)
# Проверяем, пуст ли ответ
if response.stop_reason == "end_turn" and not response.content:
# НЕПРАВИЛЬНО: не повторяйте запрос просто с пустым ответом
# Это не сработает, потому что Claude уже решил, что закончил
# ПРАВИЛЬНО: добавьте подсказку для продолжения в НОВОЕ сообщение пользователя
messages.append({"role": "user", "content": "Please continue"})
response = client.messages.create(
model="claude-opus-5-5", max_tokens=1024, messages=messages
)
return responseРекомендации:
- Никогда не добавляйте текстовые блоки сразу после результатов инструментов: это задаёт шаблон пользовательского ввода после каждого использования инструмента, и Claude следует этому шаблону, завершая свой ход.
- Не повторяйте пустые ответы без изменений: отправка пустого ответа обратно не поможет.
- Используйте подсказки для продолжения в крайнем случае: только если перечисленные исправления не решают проблему.
max_tokens
Claude остановился, потому что достиг лимита max_tokensДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape., указанного в вашем запросе.
client = anthropic.Anthropic()
# Запрос с ограниченным числом токенов
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":
# Ответ был обрезан
print("Response was cut off at token limit")
# Можно отправить ещё один запрос, чтобы продолжитьЕсли ответ Claude обрезан из-за достижения лимита max_tokens и усечённый ответ содержит незавершённый блок «tool use» (использование инструментов), вам нужно повторить запрос с большим значением max_tokens, чтобы получить полный вызов инструмента.
# Проверяем, был ли ответ обрезан во время использования инструментов
if response.stop_reason == "max_tokens":
# Проверяем, является ли последний блок контента незавершённым tool_use
last_block = response.content[-1]
if last_block.type == "tool_use":
# Отправляем запрос с увеличенным max_tokens
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096, # Increased limit
messages=messages,
tools=tools,
)stop_sequence
Claude встретил одну из ваших пользовательских стоп-последовательностейДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..
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 вызывает инструмент, который вам нужно запустить.
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":
# Извлечь и запустить инструмент
for block in response.content:
if block.type == "tool_use":
result = execute_tool(block.name, block.input)
# Вернуть результат Claude для формирования итогового ответаКогда серверный инструмент всё ещё ожидает
Claude может вызвать серверный инструмент и клиентский инструмент (инструмент, который выполняет ваш код) в одной группе параллельных вызовов инструментов. В этом случае API возвращает ответ tool_use, не выполняя серверный инструмент, чтобы вы могли сначала выполнить клиентские инструменты.
Ожидающий вызов — это блок server_tool_use или mcp_tool_use без блока результата. Больше ничто в ответе на него не указывает. После выполнения серверного инструмента его блок результата, например web_search_tool_result, содержит id вызова в своём поле tool_use_id.
Этот смешанный ответ содержит ожидающий серверный инструмент и вызов клиентского инструмента:
{
"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" }
}
]
}Чтобы продолжить после такого смешанного ответа, сформируйте последующий запрос:
- Сохраните предыдущие сообщения и добавьте
contentответа без изменений в качестве сообщенияassistant. - Добавьте пользовательское сообщение, содержащее только блоки
tool_result, по одному на каждый клиентский блокtool_use. Для ожидающего вызова блок не добавляется. - Отправьте запрос с тем же массивом
tools, что и раньше, чтобы ожидающий серверный инструмент оставался определённым.
Описание полей блока tool_result см. в разделе Обработка вызовов инструментов. Пользовательское сообщение в последующем запросе выглядит так:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
"content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
}
]
}API добавляет ваши результаты к незавершённому ходу Claude, выполняет ожидающий серверный инструмент и продолжает. Для серверного инструмента, который Claude вызвал напрямую, content следующего ответа начинается с блока результата этого инструмента.
Циклу, который выполняет описанные выше шаги для каждого ответа tool_use, не нужно обнаруживать ожидающий серверный инструмент. В последующих запросах храните в messages три отдельных сообщения в следующем порядке: первый ответ, ваше сообщение с tool_result и следующий ответ.
В двух случаях в последующем запросе требуется ещё одно поле:
- Ответ содержит
container: отправьте его ID обратно (см. раздел Повторное использование контейнера инструмента выполнения кода). - Ожидающий блок — это блок
mcp_tool_use: отправьте те жеmcp_servers, что и раньше.
Каждая из этих ошибок в последующем запросе приводит к ошибке 400 invalid_request_error. Приведённые сообщения относятся к веб-поиску. Для других серверных инструментов имена в них отличаются.
| Ошибка | Сообщение об ошибке содержит |
|---|---|
tools больше не определяет ожидающий серверный инструмент | but no `web_search` tool was provided |
Текст или другое содержимое идёт после блоков tool_result | was found without a corresponding `web_search_tool_result` block |
При программном вызове инструментов текст или другое содержимое идёт после блоков tool_result | only tool_result blocks are allowed |
Текст или другое содержимое идёт перед блоками tool_result | `tool_use` ids were found without `tool_result` blocks immediately after |
Отсутствует блок tool_result | `tool_use` ids were found without `tool_result` blocks immediately after |
Содержимое после блоков tool_result приводит к ошибке, потому что оно завершает ход Claude, пока серверный инструмент всё ещё ожидает. Чтобы передать Claude дополнительные входные данные, продолжайте, пока stop_reason ответа не будет отличаться и от tool_use, и от pause_turn. Затем отправьте эти данные новым пользовательским сообщением в том же списке messages.
pause_turn
Возвращается, когда цикл сэмплирования на стороне сервера достигает лимита итераций при выполнении серверных инструментов, таких как веб-поиск. Лимит по умолчанию составляет 10 итераций на каждый запрос.
Когда Claude останавливается, чтобы вызвать инструмент, который выполняете вы, причина остановки — tool_use, а не pause_turn.
Чтобы Claude мог завершить приостановленный ход, сформируйте новый запрос:
- Сохраните предыдущие сообщения и добавьте
contentответа без изменений в качестве сообщенияassistant, включая любой блокserver_tool_useбез блока результата. - Отправьте запрос с теми же
tools, что и раньше, и без пользовательского сообщения после сообщенияassistant.
Если ответ содержит container, также отправьте его ID обратно, чтобы ход сохранил свои файлы. Подробнее см. в разделе Повторное использование контейнера инструмента выполнения кода. В следующих примерах используется веб-поиск, и 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":
# Продолжите диалог, отправив ответ обратно
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"}],
)Ваше приложение должно обрабатывать pause_turn в любом агентном цикле, использующем серверные инструменты. Цикл, который обрабатывает повторные приостановки и отправляет ID контейнера обратно, см. в разделе Реализуйте логику повтора для pause_turn.
refusal
Claude отказался генерировать ответ. Классификаторы безопасности возвращают эту причину остановки как обычный ответ HTTP 200, а не как ошибку.
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 отказался отвечать
print("Claude was unable to process this request")
# Попробуйте переформулировать или изменить запросПри отказе объект stop_detailsДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. указывает категорию политики, которая его вызвала. Категории и полная форма ответа с отказом описаны в разделе Как выглядит отказ. stop_details имеет значение null для всех причин остановки, кроме refusal.
Отклонённый запрос обычно можно обслужить, повторив его на другой модели Claude. Это работает для Claude Fable 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 и Claude Haiku 5.5. На странице Отказы и резервная обработка показано, как настроить такой повтор — на стороне сервера или в вашем клиенте. У Claude Haiku 5.5 нет серверной резервной обработки, поэтому настройте повтор для неё с помощью резервной обработки на стороне клиента. Если вы реализуете повтор самостоятельно для запросов к любой из этих моделей, кроме Claude Haiku 5.5, на странице Кредит при резервном переключении описано, как избежать двойной оплаты кэша подсказок.
model_context_window_exceeded
Claude остановился, потому что достиг предела контекстного окна модели. Это позволяет запрашивать максимально возможное количество токенов, не зная точного размера входных данных.
client = anthropic.Anthropic()
# Запрос с максимальным числом токенов, чтобы получить как можно больше
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":
# Ответ достиг предела контекстного окна раньше, чем max_tokens
print("Response reached model's context window limit")
# Ответ по-прежнему корректен, но был ограничен контекстным окномРекомендации по обработке причин остановки
Всегда проверяйте stop_reason
Возьмите за правило проверять stop_reason в логике обработки ответов:
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 _:
# Обработка end_turn и других случаев
return next(
(block.text for block in response.content if block.type == "text"),
"",
)Корректно обрабатывайте усечённые ответы
Когда ответ усечён из-за лимитов токенов или контекстного окна, добавьте уведомление, чтобы читатель знал, что вывод неполный. Чтобы вместо этого продолжить генерацию с того места, где ответ прервался, см. раздел Обеспечение полных ответов.
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Реализуйте логику повтора для pause_turn
Когда вы используете серверные инструменты, API может вернуть pause_turn, если цикл сэмплирования на стороне сервера достигает лимита итераций (по умолчанию 10). Обработайте это, добавив приостановленный ответ в ваши сообщения без изменений и отправив запрос повторно. Если ответ содержит container, также отправьте его ID обратно. Без него следующий запрос запустит новый контейнер, и файлы, созданные ранее в этом ходе, будут потеряны.
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":
# Не приостановлено: вернуть ответ
return response
# pause_turn: добавить приостановленный ответ как сообщение assistant, затем продолжить
messages.append({"role": "assistant", "content": response.content})
# Если инструменты работали в контейнере, передать его ID обратно, чтобы сохранить его файлы
if response.container:
container_id = response.container.id
# Всё ещё приостановлено после max_requests запросов: вернуть последний ответ
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)Функция возвращает последний ответ, который содержит только заключительную часть хода. Чтобы показать весь ход или продолжить диалог, сохраняйте также и приостановленные ответы.
Причины остановки и ошибки
Важно различать значения stop_reason и настоящие ошибки:
Причины остановки (успешные ответы)
- Являются частью тела ответа
- Указывают, почему генерация штатно остановилась
- Ответ содержит корректное содержимое
Ошибки (неудачные запросы)
- Коды состояния HTTP 4xx или 5xx
- Указывают на сбои при обработке запроса
- Ответ содержит сведения об ошибке
client = anthropic.Anthropic()
try:
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
)
# Обработка успешного ответа с stop_reason
if response.stop_reason == "max_tokens":
print("Response was truncated")
except anthropic.APIStatusError as e:
# Обработка реальных ошибок
match e.status_code:
case 429:
print("Rate limit exceeded")
case 500:
print("Server error")Особенности потоковой передачи
При использовании «streaming» (потоковая передача) stop_reason:
- равен
nullв начальном событииmessage_start - передаётся в событии
message_delta - не передаётся ни в каких других событиях
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}")Распространённые шаблоны
Обработка рабочих процессов с использованием инструментов
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":
# Запускаем инструменты и продолжаем
tool_results = execute_tools(response.content)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
else:
# Итоговый ответ
return responseОбеспечение полных ответов
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
# Продолжить с того места, где произошла остановка
messages = [
{"role": "user", "content": prompt},
{"role": "assistant", "content": full_response},
{"role": "user", "content": "Please continue from where you left off."},
]
return full_responseПолучение максимального количества токенов без знания размера входных данных
Благодаря причине остановки model_context_window_exceeded вы можете запрашивать максимально возможное количество токенов, не вычисляя размер входных данных:
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":
# Получено максимально возможное число токенов с учётом размера входных данных
print(
f"Generated {response.usage.output_tokens} tokens (context limit reached)"
)
case "max_tokens":
# Получено ровно запрошенное число токенов
print(
f"Generated {response.usage.output_tokens} tokens (max_tokens reached)"
)
case _:
# Естественное завершение
print(
f"Generated {response.usage.output_tokens} tokens (natural completion)"
)
return next((block.text for block in response.content if block.type == "text"), "")Следующие шаги
Повторяйте отклонённые запросы на резервной модели — на стороне сервера или в вашем клиенте.
Позвольте SDK управлять циклом tool_use, форматированием результатов и повторными попытками за вас.
Считывайте stop_reason из события message_delta при потоковой передаче.
Обрабатывайте HTTP-ошибки 4xx и 5xx, которые отличаются от причин остановки.
Эта страница была полезной?