---
title: Razones de detención y fallback
url: https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons
description: Aprende qué significa cada valor de stop_reason y cómo manejar el truncamiento, el uso de herramientas, los turnos en pausa y los rechazos en tu aplicación.
---
Cada respuesta de la Messages API incluye un campo `stop_reason` que te indica por qué Claude dejó de generar. Revisa este campo para decidir si usar la respuesta tal cual, continuar la conversación, reintentar o recurrir a otro modelo como fallback (respaldo).
Para ver el esquema completo de la respuesta, consulta la [referencia de la Messages API](https://platform.claude.com/docs/es/api/messages/create).
## Referencia rápida
| Valor | Cuándo ocurre | Qué hacer |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`end_turn`](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#end-turn) | Claude terminó su respuesta de forma natural. | Usa la respuesta. |
| [`max_tokens`](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#max-tokens) | La respuesta alcanzó tu límite de `max_tokens`. | Aumenta `max_tokens` o [continúa la respuesta](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#ensuring-complete-responses). |
| [`stop_sequence`](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#stop-sequence) | Claude emitió una de tus `stop_sequences`. | Lee `stop_sequence` para ver cuál se activó. |
| [`tool_use`](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#tool-use) | Claude está llamando a una herramienta. | Ejecuta la herramienta y devuelve el resultado. Una llamada a una herramienta de servidor a la que aún le falta su bloque de resultado se completa en una respuesta posterior. |
| [`pause_turn`](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#pause-turn) | Un bucle de herramientas de servidor alcanzó su límite de iteraciones. | Envía de vuelta el contenido del asistente para continuar. |
| [`refusal`](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#refusal) | Claude se negó a responder. | Lee `stop_details` y [reintenta en un modelo de fallback](https://platform.claude.com/docs/es/build-with-claude/refusals-and-fallback). |
| [`model_context_window_exceeded`](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#model-context-window-exceeded) | La respuesta llenó la ventana de contexto del modelo. | Trata la respuesta como truncada. |
## El campo stop\_reason
El campo `stop_reason` forma parte de cada respuesta exitosa de la Messages API. A diferencia de los errores, que indican fallos al procesar tu solicitud, `stop_reason` te indica por qué Claude completó la generación de su respuesta.
```json 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
}
}
```
## Valores de stop reason
### end\_turn
La razón de detención más común. Indica que Claude terminó su respuesta de forma natural.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello!"}]
}' | jq 'if .stop_reason == "end_turn" then (.content[] | select(.type == "text") | .text) else . end'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello!"}' \
--format json | jq 'if .stop_reason == "end_turn" then (.content[] | select(.type == "text") | .text) else . end'
```
```python Python
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":
# Procesa la respuesta completa
for block in response.content:
if block.type == "text":
print(block.text)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
});
if (response.stop_reason === "end_turn") {
// Procesa la respuesta completa
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
}
```
```csharp C#
AnthropicClient client = new();
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello!" }]
});
if (response.StopReason == "end_turn")
{
// Procesa la respuesta completa
foreach (var block in response.Content)
{
if (block.TryPickText(out var textBlock))
{
Console.WriteLine(textBlock.Text);
}
}
}
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "end_turn" {
// Procesa la respuesta completa
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fmt.Println(textBlock.Text)
}
}
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("Hello!")
.build()
);
if (response.stopReason().map(StopReason.END_TURN::equals).orElse(false)) {
// Procesa la respuesta completa
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello!']],
model: 'claude-opus-5-5',
);
if ($response->stopReason === 'end_turn') {
// Procesa la respuesta completa
foreach ($response->content as $block) {
if ($block->type === 'text') {
echo $block->text, PHP_EOL;
}
}
}
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
)
if response.stop_reason == :end_turn
# Procesa la respuesta completa
response.content.each do |block|
puts block.text if block.type == :text
end
end
```
A veces Claude devuelve una respuesta vacía (exactamente 2–3 tokens sin contenido) con `stop_reason: "end_turn"`. Esto suele ocurrir cuando Claude interpreta que el turno del asistente está completo, particularmente después de resultados de herramientas.
**Causas comunes:**
* Agregar bloques de texto inmediatamente después de los resultados de herramientas (Claude aprende a esperar que el usuario siempre inserte texto después de los resultados de herramientas, así que termina su turno para seguir el patrón)
* Enviar de vuelta la respuesta completada de Claude sin agregar nada (Claude ya determinó que terminó, así que seguirá considerándose terminado)
**Cómo prevenir respuestas vacías:**
```python Python
# INCORRECTO: Agregar texto inmediatamente después de 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
},
],
},
]
# CORRECTO: Envía los resultados de herramientas directamente sin texto adicional
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"}
],
}, # Just the tool_result, no additional text
]
```
```typescript TypeScript
// INCORRECTO: Agregar texto inmediatamente después de tool_result
let messages: Anthropic.MessageParam[] = [
{ 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
]
}
];
// CORRECTO: Envía los resultados de herramientas directamente sin texto adicional
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",
// Solo el tool_result, sin texto adicional
content: [{ type: "tool_result", tool_use_id: "toolu_123", content: "6912" }]
}
];
```
```csharp C#
using System.Text.Json;
using Anthropic.Models.Messages;
var input = JsonSerializer.Deserialize>(
"""{"operation":"add","a":1234,"b":5678}"""
)!;
// INCORRECTO: Agregar texto inmediatamente después de tool_result
List messages =
[
new() { Role = Role.User, Content = "Calculate the sum of 1234 and 5678" },
new()
{
Role = Role.Assistant,
Content = new List
{
new ToolUseBlockParam { ID = "toolu_123", Name = "calculator", Input = input }
}
},
new()
{
Role = Role.User,
Content = new List
{
new ToolResultBlockParam { ToolUseID = "toolu_123", Content = "6912" },
new TextBlockParam { Text = "Here's the result" } // Don't add text after tool_result
}
}
];
// CORRECTO: Envía los resultados de herramientas directamente sin texto adicional
messages =
[
new() { Role = Role.User, Content = "Calculate the sum of 1234 and 5678" },
new()
{
Role = Role.Assistant,
Content = new List
{
new ToolUseBlockParam { ID = "toolu_123", Name = "calculator", Input = input }
}
},
new()
{
Role = Role.User,
// Solo el tool_result, sin texto adicional
Content = new List
{
new ToolResultBlockParam { ToolUseID = "toolu_123", Content = "6912" }
}
}
];
```
```go Go
input := map[string]any{"operation": "add", "a": 1234, "b": 5678}
// INCORRECTO: Agregar texto inmediatamente después de tool_result
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Calculate the sum of 1234 and 5678")),
anthropic.NewAssistantMessage(
anthropic.NewToolUseBlock("toolu_123", input, "calculator"),
),
anthropic.NewUserMessage(
anthropic.NewToolResultBlock("toolu_123", "6912", false),
anthropic.NewTextBlock("Here's the result"), // Don't add text after tool_result
),
}
// CORRECTO: Envía los resultados de herramientas directamente sin texto adicional
messages = []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Calculate the sum of 1234 and 5678")),
anthropic.NewAssistantMessage(
anthropic.NewToolUseBlock("toolu_123", input, "calculator"),
),
// Solo el tool_result, sin texto adicional
anthropic.NewUserMessage(
anthropic.NewToolResultBlock("toolu_123", "6912", false),
),
}
```
```java Java
ToolUseBlockParam toolUse = ToolUseBlockParam.builder()
.id("toolu_123")
.name("calculator")
.input(ToolUseBlockParam.Input.builder()
.putAdditionalProperty("operation", JsonValue.from("add"))
.putAdditionalProperty("a", JsonValue.from(1234))
.putAdditionalProperty("b", JsonValue.from(5678))
.build())
.build();
// INCORRECTO: Agregar texto inmediatamente después de tool_result
List messages = List.of(
MessageParam.builder().role(MessageParam.Role.USER)
.content("Calculate the sum of 1234 and 5678").build(),
MessageParam.builder().role(MessageParam.Role.ASSISTANT)
.contentOfBlockParams(List.of(ContentBlockParam.ofToolUse(toolUse))).build(),
MessageParam.builder().role(MessageParam.Role.USER)
.contentOfBlockParams(List.of(
ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder().toolUseId("toolu_123").content("6912").build()),
// No agregues texto después de tool_result
ContentBlockParam.ofText(TextBlockParam.builder().text("Here's the result").build())
)).build()
);
// CORRECTO: Envía los resultados de herramientas directamente sin texto adicional
messages = List.of(
MessageParam.builder().role(MessageParam.Role.USER)
.content("Calculate the sum of 1234 and 5678").build(),
MessageParam.builder().role(MessageParam.Role.ASSISTANT)
.contentOfBlockParams(List.of(ContentBlockParam.ofToolUse(toolUse))).build(),
// Solo el tool_result, sin texto adicional
MessageParam.builder().role(MessageParam.Role.USER)
.contentOfBlockParams(List.of(
ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder().toolUseId("toolu_123").content("6912").build())
)).build()
);
```
```php PHP
// INCORRECTO: Agregar texto inmediatamente después de 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'],
// No agregues texto después de tool_result
['type' => 'text', 'text' => "Here's the result"],
],
],
];
// CORRECTO: Envía los resultados de herramientas directamente sin texto adicional
$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',
// Solo el tool_result, sin texto adicional
'content' => [
['type' => 'tool_result', 'tool_use_id' => 'toolu_123', 'content' => '6912'],
],
],
];
```
```ruby Ruby
# INCORRECTO: Agregar texto inmediatamente después de 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" },
# No agregues texto después de tool_result
{ type: "text", text: "Here's the result" }
]
}
]
# CORRECTO: Envía los resultados de herramientas directamente sin texto adicional
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",
# Solo el tool_result, sin texto adicional
content: [
{ type: "tool_result", tool_use_id: "toolu_123", content: "6912" }
]
}
]
```
Si sigues obteniendo respuestas vacías después de corregir la estructura de los mensajes, agrega un prompt de continuación en un nuevo mensaje de usuario en lugar de reintentar con la respuesta vacía:
```python Python
def handle_empty_response(client, messages):
response = client.messages.create(
model="claude-opus-5-5", max_tokens=1024, messages=messages
)
# Comprueba si la respuesta está vacía
if response.stop_reason == "end_turn" and not response.content:
# INCORRECTO: No te limites a reintentar con la respuesta vacía
# Esto no funcionará porque Claude ya decidió que terminó
# CORRECTO: Agrega un prompt de continuación en un NUEVO mensaje de usuario
messages.append({"role": "user", "content": "Please continue"})
response = client.messages.create(
model="claude-opus-5-5", max_tokens=1024, messages=messages
)
return response
```
```typescript TypeScript
async function handleEmptyResponse(
client: Anthropic,
messages: Anthropic.MessageParam[]
): Promise {
let response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages
});
// Comprueba si la respuesta está vacía
if (response.stop_reason === "end_turn" && response.content.length === 0) {
// INCORRECTO: No te limites a reintentar con la respuesta vacía
// Esto no funcionará porque Claude ya decidió que terminó
// CORRECTO: Agrega un prompt de continuación en un NUEVO mensaje de usuario
messages.push({ role: "user", content: "Please continue" });
response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages
});
}
return response;
}
```
```csharp C#
static async Task HandleEmptyResponse(AnthropicClient client, List messages)
{
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = messages
});
// Comprueba si la respuesta está vacía
if (response.StopReason == "end_turn" && response.Content.Count == 0)
{
// CORRECTO: Agrega un prompt de continuación en un NUEVO mensaje de usuario
messages.Add(new() { Role = Role.User, Content = "Please continue" });
response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = messages
});
}
return response;
}
```
```go Go
func handleEmptyResponse(client anthropic.Client, messages []anthropic.MessageParam) (*anthropic.Message, error) {
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
})
if err != nil {
return nil, err
}
// Comprueba si la respuesta está vacía
if response.StopReason == "end_turn" && len(response.Content) == 0 {
// CORRECTO: Agrega un prompt de continuación en un NUEVO mensaje de usuario
messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Please continue")))
response, err = client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
})
if err != nil {
return nil, err
}
}
return response, nil
}
```
```java Java
static Message handleEmptyResponse(AnthropicClient client, List messages) {
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.messages(messages)
.build()
);
// Comprueba si la respuesta está vacía
boolean isEndTurn = response.stopReason().map(StopReason.END_TURN::equals).orElse(false);
if (isEndTurn && response.content().isEmpty()) {
// CORRECTO: Agrega un prompt de continuación en un NUEVO mensaje de usuario
List extended = new ArrayList<>(messages);
extended.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.content("Please continue")
.build());
response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.messages(extended)
.build()
);
}
return response;
}
```
```php PHP
function handle_empty_response(Client $client, array $messages)
{
$response = $client->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-opus-5-5',
);
// Comprueba si la respuesta está vacía
if ($response->stopReason === 'end_turn' && count($response->content) === 0) {
// CORRECTO: Agrega un prompt de continuación en un NUEVO mensaje de usuario
$messages[] = ['role' => 'user', 'content' => 'Please continue'];
$response = $client->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-opus-5-5',
);
}
return $response;
}
```
```ruby Ruby
def handle_empty_response(client, messages)
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: messages
)
# Verifica si la respuesta está vacía
if response.stop_reason == :end_turn && response.content.empty?
# CORRECTO: Agrega un prompt de continuación en un NUEVO mensaje de usuario
messages << { role: "user", content: "Please continue" }
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: messages
)
end
response
end
```
**Mejores prácticas:**
1. **Nunca agregues bloques de texto inmediatamente después de los resultados de herramientas:** Esto le enseña a Claude a esperar entrada del usuario después de cada uso de herramientas.
2. **No reintentes respuestas vacías sin modificación:** Enviar de vuelta la respuesta vacía no ayudará.
3. **Usa prompts de continuación como último recurso:** Solo si estas correcciones no resuelven el problema.
### max\_tokens
Claude se detuvo porque alcanzó el límite de `max_tokens` especificado en tu solicitud.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 10,
"messages": [{"role": "user", "content": "Explain quantum physics"}]
}' | jq '.stop_reason'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 10 \
--message '{role: user, content: "Explain quantum physics"}' \
--format json | jq '.stop_reason'
```
```python Python
client = anthropic.Anthropic()
# Solicitud con tokens limitados
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 respuesta se truncó
print("Response was cut off at token limit")
# Considera hacer otra solicitud para continuar
```
```typescript TypeScript
const client = new Anthropic();
// Solicitud con tokens limitados
const response = await 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 respuesta se truncó
console.log("Response was cut off at token limit");
// Considera hacer otra solicitud para continuar
}
```
```csharp C#
AnthropicClient client = new();
// Solicitud con tokens limitados
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 10,
Messages = [new() { Role = Role.User, Content = "Explain quantum physics" }]
});
if (response.StopReason == "max_tokens")
{
// La respuesta se truncó
Console.WriteLine("Response was cut off at token limit");
// Considera hacer otra solicitud para continuar
}
```
```go Go
client := anthropic.NewClient()
// Solicitud con tokens limitados
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 10,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Explain quantum physics")),
},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "max_tokens" {
// La respuesta se truncó
fmt.Println("Response was cut off at token limit")
// Considera hacer otra solicitud para continuar
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Solicitud con tokens limitados
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(10L)
.addUserMessage("Explain quantum physics")
.build()
);
if (response.stopReason().map(StopReason.MAX_TOKENS::equals).orElse(false)) {
// La respuesta se truncó
IO.println("Response was cut off at token limit");
// Considera hacer otra solicitud para continuar
}
```
```php PHP
$client = new Client();
// Solicitud con tokens limitados
$response = $client->messages->create(
maxTokens: 10,
messages: [['role' => 'user', 'content' => 'Explain quantum physics']],
model: 'claude-opus-5-5',
);
if ($response->stopReason === 'max_tokens') {
// La respuesta se truncó
echo 'Response was cut off at token limit', PHP_EOL;
// Considera hacer otra solicitud para continuar
}
```
```ruby Ruby
client = Anthropic::Client.new
# Solicitud con tokens limitados
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 respuesta se truncó
puts "Response was cut off at token limit"
# Considera hacer otra solicitud para continuar
end
```
Si la respuesta de Claude se corta porque alcanzó el límite de `max_tokens`, y la respuesta truncada contiene un bloque de uso de herramientas incompleto, tendrás que reintentar la solicitud con un valor de `max_tokens` más alto para obtener el uso de herramientas completo.
```bash CLI
RESPONSE=$(ant messages create --max-tokens 1024 --format jsonl <<'YAML'
model: claude-opus-5-5
tools:
- name: get_weather
description: Get the current weather in a given location
input_schema:
type: object
properties:
location:
type: string
required:
- location
messages:
- role: user
content: What is the weather in San Francisco?
YAML
)
# Comprueba si la respuesta se truncó a mitad del uso de herramientas
STOP_REASON=$(jq -r '.stop_reason' <<<"$RESPONSE")
LAST_TYPE=$(jq -r '.content[-1].type' <<<"$RESPONSE")
if [ "$STOP_REASON" = "max_tokens" ] && [ "$LAST_TYPE" = "tool_use" ]; then
# Reintenta con un max_tokens más alto
ant messages create --max-tokens 4096 <<'YAML'
model: claude-opus-5-5
tools:
- name: get_weather
description: Get the current weather in a given location
input_schema:
type: object
properties:
location:
type: string
required:
- location
messages:
- role: user
content: What is the weather in San Francisco?
YAML
fi
```
```python Python
# Verifica si la respuesta se truncó durante el uso de herramientas
if response.stop_reason == "max_tokens":
# Verifica si el último bloque de contenido es un tool_use incompleto
last_block = response.content[-1]
if last_block.type == "tool_use":
# Envía la solicitud con un max_tokens más alto
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096, # Increased limit
messages=messages,
tools=tools,
)
```
```typescript TypeScript
// Comprueba si la respuesta se truncó durante el uso de herramientas
if (response.stop_reason === "max_tokens") {
// Comprueba si el último bloque de contenido es un tool_use incompleto
const lastBlock = response.content[response.content.length - 1];
if (lastBlock.type === "tool_use") {
// Envía la solicitud con un max_tokens más alto
response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096, // Increased limit
messages: messages,
tools: tools
});
}
}
```
```csharp C#
using System.Linq;
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = messages,
Tools = tools
};
var response = await client.Messages.Create(parameters);
if (response.StopReason == "max_tokens")
{
var lastBlock = response.Content.Last();
if (lastBlock.TryPickToolUse(out _))
{
response = await client.Messages.Create(parameters with { MaxTokens = 4096 });
}
}
```
```go Go
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
Tools: tools,
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "max_tokens" {
lastBlock := response.Content[len(response.Content)-1]
switch lastBlock.AsAny().(type) {
case anthropic.ToolUseBlock:
response, err = client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: messages,
Tools: tools,
})
if err != nil {
log.Fatal(err)
}
}
}
```
```java Java
// Comprueba si la respuesta se truncó durante el uso de herramientas
if (response.stopReason().isPresent() && response.stopReason().get().equals(StopReason.MAX_TOKENS)) {
ContentBlock lastBlock = response.content().get(response.content().size() - 1);
if (lastBlock.toolUse().isPresent()) {
// Envía la solicitud con un max_tokens más alto
response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L) // Increased limit
.messages(messages)
.tools(tools)
.build()
);
}
}
```
```php PHP
$response = $client->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-opus-5-5',
tools: $tools,
);
if ($response->stopReason === 'max_tokens') {
$lastBlock = end($response->content);
if ($lastBlock->type === 'tool_use') {
$response = $client->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5-5',
tools: $tools,
);
}
}
```
```ruby Ruby
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: messages,
tools: tools
)
if response.stop_reason == :max_tokens
last_block = response.content.last
if last_block.type == :tool_use
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
messages: messages,
tools: tools
)
end
end
```
### stop\_sequence
Claude encontró una de tus secuencias de detención personalizadas.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"stop_sequences": ["END", "STOP"],
"messages": [{"role": "user", "content": "Generate text until you say END"}]
}' | jq '{stop_reason, stop_sequence}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 1024 \
--stop-sequence END --stop-sequence STOP \
--message '{role: user, content: "Generate text until you say END"}' \
--format json | jq '{stop_reason, stop_sequence}'
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const response = await 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") {
console.log(`Stopped at sequence: ${response.stop_sequence}`);
}
```
```csharp C#
AnthropicClient client = new();
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
StopSequences = ["END", "STOP"],
Messages = [new() { Role = Role.User, Content = "Generate text until you say END" }]
});
if (response.StopReason == "stop_sequence")
{
Console.WriteLine($"Stopped at sequence: {response.StopSequence}");
}
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
StopSequences: []string{"END", "STOP"},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Generate text until you say END")),
},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "stop_sequence" {
fmt.Printf("Stopped at sequence: %s\n", response.StopSequence)
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addStopSequence("END")
.addStopSequence("STOP")
.addUserMessage("Generate text until you say END")
.build()
);
if (response.stopReason().map(StopReason.STOP_SEQUENCE::equals).orElse(false)) {
IO.println("Stopped at sequence: " + response.stopSequence().orElse(""));
}
```
```php PHP
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Generate text until you say END']],
model: 'claude-opus-5-5',
stopSequences: ['END', 'STOP'],
);
if ($response->stopReason === 'stop_sequence') {
echo "Stopped at sequence: {$response->stopSequence}", PHP_EOL;
}
```
```ruby Ruby
client = Anthropic::Client.new
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
puts "Stopped at sequence: #{response.stop_sequence}"
end
```
### tool\_use
Claude está llamando a una herramienta y espera que la ejecutes.
Para la mayoría de las implementaciones de uso de herramientas, usa el [tool runner](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-runner), que maneja automáticamente la ejecución de herramientas, el formato de los resultados y la gestión de la conversación.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"tools": [{
"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"]
}
}],
"messages": [{"role": "user", "content": "What is the weather in San Francisco?"}]
}' | jq '.stop_reason, (.content[] | select(.type == "tool_use"))'
```
```bash CLI
ant messages create --format json <<'YAML' | jq '.stop_reason, (.content[] | select(.type == "tool_use"))'
model: claude-opus-5-5
max_tokens: 1024
messages:
- role: user
content: What is the weather in San Francisco?
tools:
- 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]
YAML
```
```python Python
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):
"""Execute 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":
# Extrae y ejecuta la herramienta
for block in response.content:
if block.type == "tool_use":
result = execute_tool(block.name, block.input)
# Devuelve el resultado a Claude para la respuesta final
```
```typescript TypeScript
const client = new Anthropic();
const weatherTool: Anthropic.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"]
}
};
function executeTool(name: string, input: Record): string {
return `Weather in ${input.location ?? "unknown"}: 72°F`;
}
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
tools: [weatherTool],
messages: [{ role: "user", content: "What is the weather in San Francisco?" }]
});
if (response.stop_reason === "tool_use") {
// Extrae y ejecuta la herramienta
for (const block of response.content) {
if (block.type === "tool_use") {
const result = executeTool(block.name, block.input as Record);
// Devuelve el resultado a Claude para la respuesta final
}
}
}
```
```csharp C#
AnthropicClient client = new();
var weatherTool = new Tool
{
Name = "get_weather",
Description = "Get the current weather in a given location",
InputSchema = new InputSchema
{
Properties = new Dictionary
{
["location"] = JsonSerializer.SerializeToElement(
new { type = "string", description = "City and state" }
),
},
Required = ["location"]
}
};
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools = [weatherTool],
Messages = [new() { Role = Role.User, Content = "What is the weather in San Francisco?" }]
});
if (response.StopReason == "tool_use")
{
// Extrae y ejecuta la herramienta
foreach (var block in response.Content)
{
if (block.TryPickToolUse(out var toolUse))
{
// Ejecuta toolUse.Name con toolUse.Input y devuelve el resultado a Claude
}
}
}
```
```go Go
client := anthropic.NewClient()
weatherTool := anthropic.ToolParam{
Name: "get_weather",
Description: anthropic.String("Get the current weather in a given location"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"location": map[string]string{"type": "string", "description": "City and state"},
},
Required: []string{"location"},
},
}
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{{OfTool: &weatherTool}},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What is the weather in San Francisco?")),
},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "tool_use" {
// Extrae y ejecuta la herramienta
for _, block := range response.Content {
if toolUse, ok := block.AsAny().(anthropic.ToolUseBlock); ok {
fmt.Println(toolUse.Name, toolUse.Input)
// Devuelve el resultado a Claude para la respuesta final
}
}
}
```
```java Java
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Tool weatherTool = Tool.builder()
.name("get_weather")
.description("Get the current weather in a given location")
.inputSchema(Tool.InputSchema.builder()
.properties(JsonValue.from(Map.of(
"location", Map.of("type", "string", "description", "City and state")
)))
.putAdditionalProperty("required", JsonValue.from(List.of("location")))
.build())
.build();
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(weatherTool)
.addUserMessage("What is the weather in San Francisco?")
.build()
);
if (response.stopReason().map(StopReason.TOOL_USE::equals).orElse(false)) {
// Extrae y ejecuta la herramienta
for (ContentBlock block : response.content()) {
block.toolUse().ifPresent(toolUse -> {
// Ejecuta toolUse.name() con toolUse.input() y devuelve el resultado a Claude
});
}
}
```
```php PHP
$client = new Client();
$weatherTool = [
'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'],
],
];
$response = $client->messages->create(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'What is the weather in San Francisco?']],
model: 'claude-opus-5-5',
tools: [$weatherTool],
);
if ($response->stopReason === 'tool_use') {
// Extrae y ejecuta la herramienta
foreach ($response->content as $block) {
if ($block->type === 'tool_use') {
// Ejecuta $block->name con $block->input y devuelve el resultado a Claude
}
}
}
```
```ruby Ruby
client = Anthropic::Client.new
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"]
}
}
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
# Extrae y ejecuta la herramienta
response.content.each do |block|
next unless block.type == :tool_use
# Ejecuta block.name con block.input y devuelve el resultado a Claude
end
end
```
Una respuesta `tool_use` también puede contener un bloque `server_tool_use` cuyo `id` no tiene un bloque de resultado correspondiente. Esa llamada a la herramienta de servidor no ha terminado, y esta respuesta no incluye su resultado. En el caso común, Claude llama a una [herramienta de servidor](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools) y a una de tus herramientas de cliente en el mismo grupo de llamadas a herramientas en paralelo: la API retorna sin ejecutar la herramienta de servidor para que puedas ejecutar primero las herramientas de cliente. No hay otro marcador para este estado; detéctalo verificando si el `id` de cada bloque `server_tool_use` o `mcp_tool_use` tiene un bloque de resultado correspondiente.
Con la [llamada programática de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/programmatic-tool-calling), la misma forma de respuesta significa algo diferente. El bloque `tool_use` de cliente proviene de código que se está ejecutando en la herramienta `code_execution` en lugar de provenir directamente de Claude, y su campo `caller` nombra el bloque `code_execution` que lo llamó. Ese código ya comenzó: está en pausa esperando tus bloques `tool_result`, y enviarlos reanuda la ejecución en lugar de iniciar una herramienta diferida. El propio bloque de resultado del bloque `code_execution` llega una vez que el código termina, lo cual puede tomar más de una ronda de resultados de herramientas. El mensaje de usuario de seguimiento en sí es el mismo en ambos casos; con la llamada programática de herramientas, también devuelve el `id` del campo `container` de la respuesta, como muestra esa página.
```json 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" }
}
]
}
```
La continuación es un mensaje de usuario de bloques `tool_result`, uno por cada bloque `tool_use` en la respuesta (consulta [Manejar llamadas a herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/handle-tool-calls)), con dos reglas adicionales: ese mensaje no debe contener nada excepto los bloques `tool_result`, y la solicitud debe mantener el mismo array `tools`. Una solicitud de reanudación que ya no define la herramienta de servidor en espera falla con un 400 cuyo mensaje termina en ``but no `web_search` tool was provided``. La API adjunta tus resultados al turno del asistente aún abierto, ejecuta la herramienta de servidor diferida (para la ejecución de código en pausa, la reanuda) y continúa el turno. Para una herramienta de servidor que Claude llamó directamente, el `content` de la siguiente respuesta comienza con el bloque de resultado que responde al `id` del `server_tool_use` de la respuesta anterior.
```json 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"
}
]
}
```
Agregar cualquier cosa después de los bloques `tool_result` en ese mensaje de usuario, como texto, termina el turno del asistente; para una herramienta de servidor que Claude llamó directamente, la solicitud entonces falla con un 400 `invalid_request_error` que nombra la herramienta de servidor sin resolver:
```text wrap
`web_search` tool use with id `srvtoolu_01HxbWnMRmbWyMfUtJKC45rA` was found without a corresponding `web_search_tool_result` block
```
Omitir un `tool_result`, o colocar uno después de otro contenido, falla antes con el error estándar `tool_use ids were found without tool_result blocks immediately after`. Para darle más entrada a Claude, envíala como un mensaje de usuario separado después de que el turno se complete.
### pause\_turn
Se devuelve cuando el bucle de muestreo del lado del servidor alcanza su límite de iteraciones mientras ejecuta [herramientas de servidor](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools) como la búsqueda web. El límite predeterminado es de 10 iteraciones por solicitud.
Cuando esto sucede, la respuesta puede contener un bloque `server_tool_use` sin un bloque de resultado correspondiente. Para permitir que Claude termine de procesar, continúa la conversación enviando de vuelta la respuesta tal cual. Una respuesta que deja un bloque `tool_use` de cliente esperándote nunca tiene un `stop_reason` de `pause_turn`: cuando Claude se detiene para llamar a tus herramientas, `stop_reason` es [`tool_use`](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#tool-use), y lo continúas enviando los bloques `tool_result` de cliente en lugar de la respuesta en sí.
```bash cURL
# Los SDK gestionan la continuación directamente. Con cURL, revisa stop_reason
# en la respuesta y vuelve a hacer POST con el contenido del asistente añadido.
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"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"}]
}' | jq '{stop_reason, content}'
```
```bash CLI
# Inspecciona stop_reason; si es pause_turn, vuelve a ejecutar con la respuesta
# del asistente añadida a --message.
ant messages create --format json <<'YAML' | jq '{stop_reason, content}'
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"}
YAML
```
```python Python
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":
# Continúa la conversación enviando la respuesta de vuelta
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"}],
)
```
```typescript TypeScript
const response = await 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") {
// Continúa la conversación enviando la respuesta de vuelta
const continuation = await 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" },
{ role: "assistant", content: response.content }
]
});
}
```
```csharp C#
List tools = [new ToolUnion(new WebSearchTool20250305())];
MessageParam userMessage = new() { Role = Role.User, Content = "Search for latest AI news" };
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Tools = tools,
Messages = [userMessage]
});
if (response.StopReason == "pause_turn")
{
// Continúa la conversación enviando la respuesta de vuelta
var continuation = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Tools = tools,
Messages =
[
userMessage,
new()
{
Role = Role.Assistant,
Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
}
]
});
}
```
```go Go
tools := []anthropic.ToolUnionParam{
{OfWebSearchTool20250305: &anthropic.WebSearchTool20250305Param{}},
}
userMessage := anthropic.NewUserMessage(anthropic.NewTextBlock("Search for latest AI news"))
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Tools: tools,
Messages: []anthropic.MessageParam{userMessage},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "pause_turn" {
// Continúa la conversación enviando la respuesta de vuelta
var contentParams []anthropic.ContentBlockParamUnion
for _, block := range response.Content {
contentParams = append(contentParams, block.ToParam())
}
continuation, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Tools: tools,
Messages: []anthropic.MessageParam{userMessage, anthropic.NewAssistantMessage(contentParams...)},
})
if err != nil {
log.Fatal(err)
}
_ = continuation
}
```
```java Java
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addTool(WebSearchTool20250305.builder().build())
.addUserMessage("Search for latest AI news")
.build()
);
if (response.stopReason().map(StopReason.PAUSE_TURN::equals).orElse(false)) {
// Continúa la conversación enviando la respuesta de vuelta
Message continuation = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addTool(WebSearchTool20250305.builder().build())
.addUserMessage("Search for latest AI news")
.addMessage(response)
.build()
);
}
```
```php PHP
$tools = [['type' => 'web_search_20250305', 'name' => 'web_search']];
$userMessage = ['role' => 'user', 'content' => 'Search for latest AI news'];
$response = $client->messages->create(
maxTokens: 4096,
messages: [$userMessage],
model: 'claude-opus-5-5',
tools: $tools,
);
if ($response->stopReason === 'pause_turn') {
// Continúa la conversación enviando la respuesta de vuelta
$continuation = $client->messages->create(
maxTokens: 4096,
messages: [
$userMessage,
['role' => 'assistant', 'content' => $response->content],
],
model: 'claude-opus-5-5',
tools: $tools,
);
}
```
```ruby Ruby
tools = [{ type: "web_search_20250305", name: "web_search" }]
user_message = { role: "user", content: "Search for latest AI news" }
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
tools: tools,
messages: [user_message]
)
if response.stop_reason == :pause_turn
# Continúa la conversación enviando la respuesta de vuelta
continuation = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
tools: tools,
messages: [user_message, { role: "assistant", content: response.content }]
)
end
```
Tu aplicación debe manejar `pause_turn` en cualquier bucle de agente que use herramientas de servidor. Agrega la respuesta del asistente a tu array de mensajes y realiza otra solicitud a la API para permitir que Claude continúe.
### refusal
Claude se negó a generar una respuesta. Los clasificadores de seguridad devuelven esta razón de detención como una respuesta HTTP 200 normal, no como un error.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "[Unsafe request]"}]
}' | jq '{stop_reason, stop_details}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "[Unsafe request]"}' \
--format json | jq '{stop_reason, stop_details}'
```
```python Python
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 se negó a responder
print("Claude was unable to process this request")
# Considera reformular o modificar la solicitud
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "[Unsafe request]" }]
});
if (response.stop_reason === "refusal") {
// Claude se negó a responder
console.log("Claude was unable to process this request");
// Considera reformular o modificar la solicitud
}
```
```csharp C#
AnthropicClient client = new();
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "[Unsafe request]" }]
});
if (response.StopReason == "refusal")
{
// Claude se negó a responder
Console.WriteLine("Claude was unable to process this request");
// Considera reformular o modificar la solicitud
}
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("[Unsafe request]")),
},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "refusal" {
// Claude se negó a responder
fmt.Println("Claude was unable to process this request")
// Considera reformular o modificar la solicitud
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("[Unsafe request]")
.build()
);
if (response.stopReason().map(StopReason.REFUSAL::equals).orElse(false)) {
// Claude se negó a responder
IO.println("Claude was unable to process this request");
// Considera reformular o modificar la solicitud
}
```
```php PHP
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => '[Unsafe request]']],
model: 'claude-opus-5-5',
);
if ($response->stopReason === 'refusal') {
// Claude se negó a responder
echo 'Claude was unable to process this request', PHP_EOL;
// Considera reformular o modificar la solicitud
}
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "[Unsafe request]" }]
)
if response.stop_reason == :refusal
# Claude se negó a responder
puts "Claude was unable to process this request"
# Considera reformular o modificar la solicitud
end
```
Si encuentras razones de detención `refusal` con frecuencia al usar Claude Sonnet 4.5 ([obsoleto](https://platform.claude.com/docs/es/about-claude/model-deprecations)) o Claude Opus 4.1 (este último [retirado, excepto en Bedrock y Google Cloud](https://platform.claude.com/docs/es/about-claude/model-deprecations)), puedes intentar actualizar tus llamadas a la API para usar Haiku 4.5 (`claude-haiku-4-5-20251001`), que tiene restricciones de uso diferentes. Obtén más información sobre [cómo entender los filtros de seguridad de la API de Sonnet 4.5](https://support.claude.com/en/articles/12449294-understanding-sonnet-4-5-s-api-safety-filters).
En un rechazo, el objeto `stop_details` identifica la categoría de política que lo activó. Las categorías y la forma completa de la respuesta de rechazo se cubren en [Rechazos y fallback](https://platform.claude.com/docs/es/build-with-claude/refusals-and-fallback#refusal-response). `stop_details` es `null` para todas las razones de detención distintas de `refusal`.
Una solicitud rechazada en Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 o Claude Haiku 5.5 normalmente puede atenderse reintentando en otro modelo de Claude. [Rechazos y fallback](https://platform.claude.com/docs/es/build-with-claude/refusals-and-fallback) muestra cómo configurar ese reintento, del lado del servidor o en tu cliente. Claude Haiku 5.5 no tiene fallback del lado del servidor, así que configura su reintento [en tu cliente](https://platform.claude.com/docs/es/build-with-claude/refusals-and-fallback#client-side-fallback). Si construyes el reintento tú mismo desde Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5 o Claude Sonnet 5.5, el [crédito de fallback](https://platform.claude.com/docs/es/build-with-claude/fallback-credit) explica cómo evitar pagar dos veces el costo de la caché de prompts.
### model\_context\_window\_exceeded
Claude se detuvo porque alcanzó el límite de la ventana de contexto del modelo. Esto te permite solicitar el máximo posible de tokens sin conocer el tamaño exacto de la entrada.
Esta razón de detención actualmente solo está tipada en el espacio de nombres `beta` (csharp, go: `Beta`; java: `beta()`) del SDK, por lo que los siguientes ejemplos llaman a `client.beta.messages` (csharp, go: `client.Beta.Messages`; java: `client.beta().messages()`; php: `$client->beta->messages`) y usan los tipos con el prefijo `Beta`. En Sonnet 4.5 (obsoleto) y modelos más recientes, la API devuelve este valor sin un encabezado beta. Para modelos anteriores, agrega el encabezado beta `model-context-window-exceeded-2025-08-26` para habilitarlo.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 20000,
"messages": [{"role": "user", "content": "Large input that uses most of context window..."}]
}' | jq '.stop_reason'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 20000 \
--message '{role: user, content: "Large input that uses most of context window..."}' \
--format json | jq '.stop_reason'
```
```python Python
# Solicitud con el máximo de tokens para obtener lo más posible
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 respuesta alcanzó el límite de la ventana de contexto antes de max_tokens
print("Response reached model's context window limit")
# La respuesta sigue siendo válida, pero quedó limitada por la ventana de contexto
```
```typescript TypeScript
// Solicitud con el máximo de tokens para obtener lo más posible
const response = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 20000,
messages: [{ role: "user", content: "Large input that uses most of context window..." }]
});
if (response.stop_reason === "model_context_window_exceeded") {
// La respuesta alcanzó el límite de la ventana de contexto antes de max_tokens
console.log("Response reached model's context window limit");
// La respuesta sigue siendo válida, pero quedó limitada por la ventana de contexto
}
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Model = Anthropic.Models.Messages.Model;
// Solicitud con el máximo de tokens para obtener lo más posible
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 20000,
Messages = [new() { Role = Role.User, Content = "Large input that uses most of context window..." }]
});
if (response.StopReason?.Value() == BetaStopReason.ModelContextWindowExceeded)
{
// La respuesta alcanzó el límite de la "context window" (ventana de contexto) antes de max_tokens
Console.WriteLine("Response reached model's context window limit");
// La respuesta sigue siendo válida, pero quedó limitada por la ventana de contexto
}
```
```go Go
// Solicitud con el máximo de tokens para obtener lo más posible
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 20000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Large input that uses most of context window...")),
},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == anthropic.BetaStopReasonModelContextWindowExceeded {
// La respuesta alcanzó el límite de la ventana de contexto antes de max_tokens
fmt.Println("Response reached model's context window limit")
// La respuesta sigue siendo válida, pero quedó limitada por la ventana de contexto
}
```
```java Java
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaStopReason;
import com.anthropic.models.beta.messages.MessageCreateParams;
// Solicitud con el máximo de tokens para obtener lo más posible
BetaMessage response = client.beta().messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(20000L)
.addUserMessage("Large input that uses most of context window...")
.build()
);
if (response.stopReason().map(BetaStopReason.MODEL_CONTEXT_WINDOW_EXCEEDED::equals).orElse(false)) {
// La respuesta alcanzó el límite de la ventana de contexto antes de max_tokens
IO.println("Response reached model's context window limit");
// La respuesta sigue siendo válida, pero quedó limitada por la ventana de contexto
}
```
```php PHP
// Solicitud con el máximo de tokens para obtener lo más posible
$response = $client->beta->messages->create(
maxTokens: 20000,
messages: [['role' => 'user', 'content' => 'Large input that uses most of context window...']],
model: 'claude-opus-5-5',
);
if ($response->stopReason === 'model_context_window_exceeded') {
// La respuesta alcanzó el límite de la ventana de contexto antes de max_tokens
echo 'Response reached model\'s context window limit', PHP_EOL;
// La respuesta sigue siendo válida, pero quedó limitada por la ventana de contexto
}
```
```ruby Ruby
# Solicitud con el máximo de tokens para obtener lo más posible
response = client.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 20000,
messages: [{ role: "user", content: "Large input that uses most of context window..." }]
)
if response.stop_reason == :model_context_window_exceeded
# La respuesta alcanzó el límite de la ventana de contexto antes de max_tokens
puts "Response reached model's context window limit"
# La respuesta sigue siendo válida, pero quedó limitada por la ventana de contexto
end
```
## Mejores prácticas para manejar las razones de detención
### Siempre revisa stop\_reason
Acostúmbrate a revisar el `stop_reason` en tu lógica de manejo de respuestas:
```python Python
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 _:
# Maneja end_turn y otros casos
return next(
(block.text for block in response.content if block.type == "text"),
"",
)
```
```typescript TypeScript
function handleResponse(response: Anthropic.Beta.BetaMessage): string {
switch (response.stop_reason) {
case "tool_use":
return handleToolUse(response);
case "max_tokens":
return handleTruncation(response);
case "model_context_window_exceeded":
return handleContextLimit(response);
case "pause_turn":
return handlePause(response);
case "refusal":
return handleRefusal(response);
default: {
// Maneja end_turn y otros casos
const textBlock = response.content.find(
(block): block is Anthropic.Beta.BetaTextBlock => block.type === "text"
);
return textBlock?.text ?? "";
}
}
}
```
```csharp C#
static string HandleResponse(BetaMessage response)
{
return response.StopReason?.Value() switch
{
BetaStopReason.ToolUse => HandleToolUse(response),
BetaStopReason.MaxTokens => HandleTruncation(response),
BetaStopReason.ModelContextWindowExceeded => HandleContextLimit(response),
BetaStopReason.PauseTurn => HandlePause(response),
BetaStopReason.Refusal => HandleRefusal(response),
// Maneja end_turn y otros casos
_ => response.Content.Select(b => b.Value).OfType().FirstOrDefault()?.Text ?? "",
};
}
```
```go Go
func handleResponse(response *anthropic.BetaMessage) string {
switch response.StopReason {
case anthropic.BetaStopReasonToolUse:
return handleToolUse(response)
case anthropic.BetaStopReasonMaxTokens:
return handleTruncation(response)
case anthropic.BetaStopReasonModelContextWindowExceeded:
return handleContextLimit(response)
case anthropic.BetaStopReasonPauseTurn:
return handlePause(response)
case anthropic.BetaStopReasonRefusal:
return handleRefusal(response)
default:
// Maneja end_turn y otros casos
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
return textBlock.Text
}
}
return ""
}
}
```
```java Java
static String handleResponse(BetaMessage response) {
BetaStopReason reason = response.stopReason().orElse(BetaStopReason.END_TURN);
if (reason.equals(BetaStopReason.TOOL_USE)) {
return handleToolUse(response);
} else if (reason.equals(BetaStopReason.MAX_TOKENS)) {
return handleTruncation(response);
} else if (reason.equals(BetaStopReason.MODEL_CONTEXT_WINDOW_EXCEEDED)) {
return handleContextLimit(response);
} else if (reason.equals(BetaStopReason.PAUSE_TURN)) {
return handlePause(response);
} else if (reason.equals(BetaStopReason.REFUSAL)) {
return handleRefusal(response);
}
// Maneja end_turn y otros casos
return response.content().stream()
.filter(BetaContentBlock::isText)
.findFirst()
.map(block -> block.asText().text())
.orElse("");
}
```
```php PHP
function handle_response($response): string
{
return match ($response->stopReason) {
'tool_use' => handle_tool_use($response),
'max_tokens' => handle_truncation($response),
'model_context_window_exceeded' => handle_context_limit($response),
'pause_turn' => handle_pause($response),
'refusal' => handle_refusal($response),
// Maneja end_turn y otros casos
default => array_find($response->content, static fn ($block): bool => $block->type === 'text')?->text ?? '',
};
}
```
```ruby Ruby
def handle_response(response)
case response.stop_reason
when :tool_use then handle_tool_use(response)
when :max_tokens then handle_truncation(response)
when :model_context_window_exceeded then handle_context_limit(response)
when :pause_turn then handle_pause(response)
when :refusal then handle_refusal(response)
else
# Maneja end_turn y otros casos
response.content.find { it.type == :text }&.text
end
end
```
### Maneja las respuestas truncadas con elegancia
Cuando una respuesta se trunca debido a los límites de tokens o a la ventana de contexto, agrega un aviso para que el lector sepa que la salida está incompleta. Para continuar generando desde donde se quedó la respuesta, consulta [Asegurar respuestas completas](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#ensuring-complete-responses).
```python Python
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
```
```typescript TypeScript
function handleTruncatedResponse(response: Anthropic.Beta.BetaMessage): string {
const textBlock = response.content.find(
(block): block is Anthropic.Beta.BetaTextBlock => block.type === "text"
);
const text = textBlock?.text ?? "";
if (
response.stop_reason === "max_tokens" ||
response.stop_reason === "model_context_window_exceeded"
) {
const note =
response.stop_reason === "max_tokens"
? "[Response truncated due to max_tokens limit]"
: "[Response truncated due to context window limit]";
return `${text}\n\n${note}`;
}
return text;
}
```
```csharp C#
static string HandleTruncatedResponse(BetaMessage response)
{
var text = response.Content.Select(b => b.Value).OfType().FirstOrDefault()?.Text ?? "";
var reason = response.StopReason?.Value();
if (reason is BetaStopReason.MaxTokens or BetaStopReason.ModelContextWindowExceeded)
{
var note = reason == BetaStopReason.MaxTokens
? "[Response truncated due to max_tokens limit]"
: "[Response truncated due to context window limit]";
return $"{text}\n\n{note}";
}
return text;
}
```
```go Go
func handleTruncatedResponse(response *anthropic.BetaMessage) string {
text := ""
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
text = textBlock.Text
break
}
}
if response.StopReason == anthropic.BetaStopReasonMaxTokens ||
response.StopReason == anthropic.BetaStopReasonModelContextWindowExceeded {
note := "[Response truncated due to context window limit]"
if response.StopReason == anthropic.BetaStopReasonMaxTokens {
note = "[Response truncated due to max_tokens limit]"
}
return text + "\n\n" + note
}
return text
}
```
```java Java
static String handleTruncatedResponse(BetaMessage response) {
String text = response.content().stream()
.filter(BetaContentBlock::isText)
.findFirst()
.map(block -> block.asText().text())
.orElse("");
BetaStopReason reason = response.stopReason().orElse(BetaStopReason.END_TURN);
if (reason.equals(BetaStopReason.MAX_TOKENS)
|| reason.equals(BetaStopReason.MODEL_CONTEXT_WINDOW_EXCEEDED)) {
String note = reason.equals(BetaStopReason.MAX_TOKENS)
? "[Response truncated due to max_tokens limit]"
: "[Response truncated due to context window limit]";
return text + "\n\n" + note;
}
return text;
}
```
```php PHP
function handle_truncated_response($response): string
{
$text = array_find($response->content, static fn ($block): bool => $block->type === 'text')?->text ?? '';
if (in_array($response->stopReason, ['max_tokens', 'model_context_window_exceeded'], true)) {
$note = $response->stopReason === 'max_tokens'
? '[Response truncated due to max_tokens limit]'
: '[Response truncated due to context window limit]';
return "{$text}\n\n{$note}";
}
return $text;
}
```
```ruby Ruby
def handle_truncated_response(response)
text = response.content.find { it.type == :text }&.text
if [:max_tokens, :model_context_window_exceeded].include?(response.stop_reason)
note = if response.stop_reason == :max_tokens
"[Response truncated due to max_tokens limit]"
else
"[Response truncated due to context window limit]"
end
return "#{text}\n\n#{note}"
end
text
end
```
### Implementa lógica de reintento para pause\_turn
Al usar [herramientas de servidor](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools), la API puede devolver `pause_turn` si el bucle de muestreo del lado del servidor alcanza su límite de iteraciones (10 por defecto). Maneja esto continuando la conversación:
```python Python
def handle_server_tool_conversation(client, user_query, tools, max_continuations=5):
"""
Handle server tool conversations that may require multiple continuations.
The server runs a sampling loop when executing server tools. If the loop
reaches its iteration limit, the API returns pause_turn. Continue the
conversation by sending the response back to let Claude finish.
"""
messages = [{"role": "user", "content": user_query}]
for _ in range(max_continuations):
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=messages,
tools=tools,
)
if response.stop_reason != "pause_turn":
# Claude terminó de procesar: devuelve la respuesta final
return response
# pause_turn: reemplaza la lista completa de mensajes para mantener la alternancia de roles
messages = [
{"role": "user", "content": user_query},
{"role": "assistant", "content": response.content},
]
# Se alcanzó el máximo de continuaciones: devuelve la última respuesta
return response
```
```typescript TypeScript
async function handleServerToolConversation(
client: Anthropic,
userQuery: string,
tools: Anthropic.ToolUnion[],
maxContinuations = 5
): Promise {
let messages: Anthropic.MessageParam[] = [{ role: "user", content: userQuery }];
let response: Anthropic.Message;
for (let i = 0; i < maxContinuations; i++) {
response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
messages,
tools
});
if (response.stop_reason !== "pause_turn") {
// Claude terminó de procesar: devuelve la respuesta final
return response;
}
// pause_turn: reemplaza toda la lista de mensajes para mantener roles alternados
messages = [
{ role: "user", content: userQuery },
{ role: "assistant", content: response.content }
];
}
// Se alcanzó el máximo de continuaciones: devuelve la última respuesta
return response!;
}
```
```csharp C#
static async Task HandleServerToolConversation(
AnthropicClient client,
string userQuery,
List tools,
int maxContinuations = 5)
{
List messages = [new() { Role = Role.User, Content = userQuery }];
Message response = null!;
for (var i = 0; i < maxContinuations; i++)
{
response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = messages,
Tools = tools
});
if (response.StopReason != "pause_turn")
{
// Claude terminó de procesar: devuelve la respuesta final
return response;
}
// pause_turn: reemplaza la lista completa de mensajes para mantener los roles alternados
messages =
[
new() { Role = Role.User, Content = userQuery },
new()
{
Role = Role.Assistant,
Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
}
];
}
// Se alcanzó el máximo de continuaciones: devuelve la última respuesta
return response;
}
```
```go Go
func handleServerToolConversation(
client anthropic.Client,
userQuery string,
tools []anthropic.ToolUnionParam,
maxContinuations int,
) (*anthropic.Message, error) {
messages := []anthropic.MessageParam{anthropic.NewUserMessage(anthropic.NewTextBlock(userQuery))}
var response *anthropic.Message
var err error
for range maxContinuations {
response, err = client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: messages,
Tools: tools,
})
if err != nil {
return nil, err
}
if response.StopReason != "pause_turn" {
// Claude terminó de procesar: devuelve la respuesta final
return response, nil
}
// pause_turn: reemplaza toda la lista de mensajes para mantener roles alternados
var contentParams []anthropic.ContentBlockParamUnion
for _, block := range response.Content {
contentParams = append(contentParams, block.ToParam())
}
messages = []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(userQuery)),
anthropic.NewAssistantMessage(contentParams...),
}
}
// Se alcanzó el máximo de continuaciones: devuelve la última respuesta
return response, nil
}
```
```java Java
static Message handleServerToolConversation(
AnthropicClient client,
String userQuery,
List tools,
int maxContinuations
) {
Message response = null;
for (int i = 0; i < maxContinuations; i++) {
// Reconstruye los parámetros en cada iteración para que los mensajes no se acumulen
MessageCreateParams.Builder params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addUserMessage(userQuery);
tools.forEach(params::addTool);
if (response != null) {
params.addMessage(response);
}
response = client.messages().create(params.build());
if (!response.stopReason().map(StopReason.PAUSE_TURN::equals).orElse(false)) {
// Claude terminó de procesar: devuelve la respuesta final
return response;
}
// pause_turn: repite el bucle y envía la respuesta de vuelta
}
// Se alcanzó el máximo de continuaciones: devuelve la última respuesta
return response;
}
```
```php PHP
function handle_server_tool_conversation(
Client $client,
string $userQuery,
array $tools,
int $maxContinuations = 5
) {
$messages = [['role' => 'user', 'content' => $userQuery]];
$response = null;
for ($i = 0; $i < $maxContinuations; $i++) {
$response = $client->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5-5',
tools: $tools,
);
if ($response->stopReason !== 'pause_turn') {
// Claude terminó de procesar: devuelve la respuesta final
return $response;
}
// pause_turn: reemplaza toda la lista de mensajes para mantener roles alternados
$messages = [
['role' => 'user', 'content' => $userQuery],
['role' => 'assistant', 'content' => $response->content],
];
}
// Se alcanzó el máximo de continuaciones: devuelve la última respuesta
return $response;
}
```
```ruby Ruby
def handle_server_tool_conversation(client, user_query, tools, max_continuations: 5)
messages = [{ role: "user", content: user_query }]
response = nil
max_continuations.times do
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
messages: messages,
tools: tools
)
# Claude terminó de procesar: devuelve la respuesta final
return response unless response.stop_reason == :pause_turn
# pause_turn: reemplaza la lista completa de mensajes para mantener la alternancia de roles
messages = [
{ role: "user", content: user_query },
{ role: "assistant", content: response.content }
]
end
# Se alcanzó el máximo de continuaciones: devuelve la última respuesta
response
end
```
## Razones de detención vs. errores
Es importante distinguir entre los valores de `stop_reason` y los errores reales:
### Razones de detención (respuestas exitosas)
* Forman parte del cuerpo de la respuesta
* Indican por qué la generación se detuvo normalmente
* La respuesta contiene contenido válido
### Errores (solicitudes fallidas)
* Códigos de estado HTTP 4xx o 5xx
* Indican fallos en el procesamiento de la solicitud
* La respuesta contiene detalles del error
```bash cURL
# cURL sale con código distinto de cero ante errores HTTP con --fail-with-body; revisa
# $? para detectar errores y stop_reason para las respuestas exitosas.
curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello!"}]
}' | jq '.stop_reason'
```
```bash CLI
# La CLI termina con código distinto de cero ante errores de la API; stop_reason aparece si tiene éxito.
ant messages create \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello!"}' \
--format json | jq '.stop_reason'
```
```python Python
client = anthropic.Anthropic()
try:
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
)
# Maneja la respuesta exitosa con stop_reason
if response.stop_reason == "max_tokens":
print("Response was truncated")
except anthropic.APIStatusError as e:
# Maneja los errores reales
match e.status_code:
case 429:
print("Rate limit exceeded")
case 500:
print("Server error")
```
```typescript TypeScript
const client = new Anthropic();
try {
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
});
// Maneja la respuesta exitosa con stop_reason
if (response.stop_reason === "max_tokens") {
console.log("Response was truncated");
}
} catch (err) {
// Maneja los errores reales
if (err instanceof Anthropic.APIError) {
switch (err.status) {
case 429:
console.log("Rate limit exceeded");
break;
case 500:
console.log("Server error");
break;
}
} else {
throw err;
}
}
```
```csharp C#
AnthropicClient client = new();
try
{
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello!" }]
});
// Maneja la respuesta exitosa con stop_reason
if (response.StopReason == "max_tokens")
{
Console.WriteLine("Response was truncated");
}
}
catch (AnthropicRateLimitException)
{
// Maneja los errores reales
Console.WriteLine("Rate limit exceeded");
}
catch (Anthropic5xxException)
{
Console.WriteLine("Server error");
}
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
},
})
if err != nil {
// Maneja los errores reales
var apiErr *anthropic.Error
if errors.As(err, &apiErr) {
switch apiErr.StatusCode {
case 429:
fmt.Println("Rate limit exceeded")
case 500:
fmt.Println("Server error")
}
}
log.Fatal(err)
}
// Maneja la respuesta exitosa con stop_reason
if response.StopReason == "max_tokens" {
fmt.Println("Response was truncated")
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
try {
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("Hello!")
.build()
);
// Maneja la respuesta exitosa con stop_reason
if (response.stopReason().map(StopReason.MAX_TOKENS::equals).orElse(false)) {
IO.println("Response was truncated");
}
} catch (RateLimitException e) {
// Maneja los errores reales
IO.println("Rate limit exceeded");
} catch (AnthropicServiceException e) {
if (e.statusCode() == 500) {
IO.println("Server error");
}
}
```
```php PHP
$client = new Client();
try {
$response = $client->messages->create(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello!']],
model: 'claude-opus-5-5',
);
// Maneja la respuesta exitosa con stop_reason
if ($response->stopReason === 'max_tokens') {
echo 'Response was truncated', PHP_EOL;
}
} catch (RateLimitException $e) {
// Maneja los errores reales
echo 'Rate limit exceeded', PHP_EOL;
} catch (InternalServerException $e) {
echo 'Server error', PHP_EOL;
}
```
```ruby Ruby
client = Anthropic::Client.new
begin
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
)
# Maneja la respuesta exitosa con stop_reason
if response.stop_reason == :max_tokens
puts "Response was truncated"
end
rescue Anthropic::Errors::RateLimitError
# Maneja los errores reales
puts "Rate limit exceeded"
rescue Anthropic::Errors::APIStatusError => e
puts "Server error" if e.status == 500
end
```
## Consideraciones sobre streaming
Al usar streaming, `stop_reason`:
* Es `null` en el evento inicial `message_start`
* Se proporciona en el evento `message_delta`
* No se proporciona en ningún otro evento
```bash cURL
# El evento message_delta del stream SSE contiene stop_reason.
curl --no-buffer https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"stream": true,
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```bash CLI
# stop_reason aparece en el evento message_delta.
ant messages create --stream --format jsonl \
--model claude-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello!"}' |
jq -c 'select(.type == "message_delta") | .delta.stop_reason'
```
```python Python
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}")
```
```typescript TypeScript
const client = new Anthropic();
const stream = client.messages.stream({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
});
for await (const event of stream) {
if (event.type === "message_delta" && event.delta.stop_reason) {
console.log(`Stream ended with: ${event.delta.stop_reason}`);
}
}
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello!" }]
};
await foreach (var streamEvent in client.Messages.CreateStreaming(parameters))
{
switch (streamEvent.Value)
{
case RawMessageDeltaEvent deltaEvent when deltaEvent.Delta.StopReason is not null:
Console.WriteLine($"Stream ended with: {deltaEvent.Delta.StopReason}");
break;
}
}
```
```go Go
client := anthropic.NewClient()
stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
},
})
// Acumula los eventos en el Message final, que incluye stop_reason.
message := anthropic.Message{}
for stream.Next() {
if err := message.Accumulate(stream.Current()); err != nil {
log.Fatal(err)
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
if message.StopReason != "" {
fmt.Printf("Stream ended with: %s\n", message.StopReason)
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("Hello!")
.build();
// Acumula los eventos en el Message final, que incluye stop_reason.
MessageAccumulator accumulator = MessageAccumulator.create();
try (StreamResponse streamResponse =
client.messages().createStreaming(params)) {
streamResponse.stream().forEach(accumulator::accumulate);
}
accumulator.message().stopReason().ifPresent(stopReason ->
IO.println("Stream ended with: " + stopReason)
);
```
```php PHP
$client = new Client();
$stream = $client->messages->createStream(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello!']],
model: 'claude-opus-5-5',
);
foreach ($stream as $event) {
if ($event instanceof \Anthropic\Messages\RawMessageDeltaEvent && $event->delta->stopReason !== null) {
echo "Stream ended with: {$event->delta->stopReason}", PHP_EOL;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
stream = client.messages.stream(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
)
stream.each do |event|
next unless event.type == :message_delta
stop_reason = event.delta.stop_reason
puts "Stream ended with: #{stop_reason}" if stop_reason
end
```
## Patrones comunes
### Manejo de flujos de trabajo de uso de herramientas
**Más simple con el tool runner:** El siguiente ejemplo muestra el manejo manual de herramientas. Para la mayoría de los casos de uso, el [tool runner](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-runner) maneja automáticamente la ejecución de herramientas con mucho menos código.
```python Python
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":
# Ejecuta las herramientas y continúa
tool_results = execute_tools(response.content)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
else:
# Respuesta final
return response
```
```typescript TypeScript
async function completeToolWorkflow(
client: Anthropic,
userQuery: string,
tools: Anthropic.ToolUnion[]
): Promise {
const messages: Anthropic.MessageParam[] = [{ role: "user", content: userQuery }];
while (true) {
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages,
tools
});
if (response.stop_reason === "tool_use") {
// Ejecuta las herramientas y continúa
const toolResults = executeTools(response.content);
messages.push({ role: "assistant", content: response.content });
messages.push({ role: "user", content: toolResults });
} else {
// Respuesta final
return response;
}
}
}
```
```csharp C#
static async Task CompleteToolWorkflow(
AnthropicClient client,
string userQuery,
List tools)
{
List messages = [new() { Role = Role.User, Content = userQuery }];
while (true)
{
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = messages,
Tools = tools
});
if (response.StopReason == "tool_use")
{
// Ejecuta las herramientas y continúa
var toolResults = ExecuteTools(response.Content);
messages.Add(new()
{
Role = Role.Assistant,
Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
});
messages.Add(new() { Role = Role.User, Content = toolResults });
}
else
{
// Respuesta final
return response;
}
}
}
```
```go Go
func completeToolWorkflow(
client anthropic.Client,
userQuery string,
tools []anthropic.ToolUnionParam,
) (*anthropic.Message, error) {
messages := []anthropic.MessageParam{anthropic.NewUserMessage(anthropic.NewTextBlock(userQuery))}
for {
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
Tools: tools,
})
if err != nil {
return nil, err
}
if response.StopReason != "tool_use" {
// Respuesta final
return response, nil
}
// Ejecuta las herramientas y continúa
toolResults := executeTools(response.Content)
var contentParams []anthropic.ContentBlockParamUnion
for _, block := range response.Content {
contentParams = append(contentParams, block.ToParam())
}
messages = append(messages, anthropic.NewAssistantMessage(contentParams...))
messages = append(messages, anthropic.NewUserMessage(toolResults...))
}
}
```
```java Java
static Message completeToolWorkflow(
AnthropicClient client,
String userQuery,
List tools
) {
List messages = new ArrayList<>();
messages.add(MessageParam.builder().role(MessageParam.Role.USER).content(userQuery).build());
while (true) {
MessageCreateParams.Builder params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.messages(messages);
tools.forEach(params::addTool);
Message response = client.messages().create(params.build());
if (!response.stopReason().map(StopReason.TOOL_USE::equals).orElse(false)) {
// Respuesta final
return response;
}
// Ejecuta las herramientas y continúa
List toolResults = executeTools(response.content());
messages.add(response.toParam());
messages.add(MessageParam.builder()
.role(MessageParam.Role.USER)
.contentOfBlockParams(toolResults.stream().map(ContentBlockParam::ofToolResult).toList())
.build());
}
}
```
```php PHP
function complete_tool_workflow(Client $client, string $userQuery, array $tools)
{
$messages = [['role' => 'user', 'content' => $userQuery]];
while (true) {
$response = $client->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-opus-5-5',
tools: $tools,
);
if ($response->stopReason !== 'tool_use') {
// Respuesta final
return $response;
}
// Ejecuta las herramientas y continúa
$toolResults = execute_tools($response->content);
$messages[] = ['role' => 'assistant', 'content' => $response->content];
$messages[] = ['role' => 'user', 'content' => $toolResults];
}
}
```
```ruby Ruby
def complete_tool_workflow(client, user_query, tools)
messages = [{ role: "user", content: user_query }]
loop do
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: messages,
tools: tools
)
# Respuesta final
return response unless response.stop_reason == :tool_use
# Ejecuta las herramientas y continúa
tool_results = execute_tools(response.content)
messages << { role: "assistant", content: response.content }
messages << { role: "user", content: tool_results }
end
end
```
### Asegurar respuestas completas
```python Python
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
# Continúa desde donde se quedó
messages = [
{"role": "user", "content": prompt},
{"role": "assistant", "content": full_response},
{"role": "user", "content": "Please continue from where you left off."},
]
return full_response
```
```typescript TypeScript
async function getCompleteResponse(
client: Anthropic,
prompt: string,
maxAttempts = 3
): Promise {
let messages: Anthropic.MessageParam[] = [{ role: "user", content: prompt }];
let fullResponse = "";
for (let i = 0; i < maxAttempts; i++) {
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
messages
});
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
fullResponse += textBlock?.text ?? "";
if (response.stop_reason !== "max_tokens") {
break;
}
// Continúa desde donde se quedó
messages = [
{ role: "user", content: prompt },
{ role: "assistant", content: fullResponse },
{ role: "user", content: "Please continue from where you left off." }
];
}
return fullResponse;
}
```
```csharp C#
static async Task GetCompleteResponse(AnthropicClient client, string prompt, int maxAttempts = 3)
{
List messages = [new() { Role = Role.User, Content = prompt }];
var fullResponse = "";
for (var i = 0; i < maxAttempts; i++)
{
var response = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = messages
});
foreach (var block in response.Content)
{
if (block.TryPickText(out var textBlock))
{
fullResponse += textBlock.Text;
break;
}
}
if (response.StopReason != "max_tokens")
{
break;
}
// Continúa desde donde se quedó
messages =
[
new() { Role = Role.User, Content = prompt },
new() { Role = Role.Assistant, Content = fullResponse },
new() { Role = Role.User, Content = "Please continue from where you left off." }
];
}
return fullResponse;
}
```
```go Go
func getCompleteResponse(client anthropic.Client, prompt string, maxAttempts int) (string, error) {
messages := []anthropic.MessageParam{anthropic.NewUserMessage(anthropic.NewTextBlock(prompt))}
fullResponse := ""
for range maxAttempts {
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: messages,
})
if err != nil {
return "", err
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fullResponse += textBlock.Text
break
}
}
if response.StopReason != "max_tokens" {
break
}
// Continúa desde donde se quedó
messages = []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(prompt)),
anthropic.NewAssistantMessage(anthropic.NewTextBlock(fullResponse)),
anthropic.NewUserMessage(anthropic.NewTextBlock("Please continue from where you left off.")),
}
}
return fullResponse, nil
}
```
```java Java
static String getCompleteResponse(AnthropicClient client, String prompt, int maxAttempts) {
List messages = List.of(
MessageParam.builder().role(MessageParam.Role.USER).content(prompt).build()
);
StringBuilder fullResponse = new StringBuilder();
for (int i = 0; i < maxAttempts; i++) {
Message response = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.messages(messages)
.build()
);
response.content().stream()
.filter(ContentBlock::isText)
.findFirst()
.ifPresent(block -> fullResponse.append(block.asText().text()));
if (!response.stopReason().map(StopReason.MAX_TOKENS::equals).orElse(false)) {
break;
}
// Continúa desde donde se quedó
messages = List.of(
MessageParam.builder().role(MessageParam.Role.USER).content(prompt).build(),
MessageParam.builder().role(MessageParam.Role.ASSISTANT).content(fullResponse.toString()).build(),
MessageParam.builder().role(MessageParam.Role.USER).content("Please continue from where you left off.").build()
);
}
return fullResponse.toString();
}
```
```php PHP
function get_complete_response(Client $client, string $prompt, int $maxAttempts = 3): string
{
$messages = [['role' => 'user', 'content' => $prompt]];
$fullResponse = '';
for ($i = 0; $i < $maxAttempts; $i++) {
$response = $client->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5-5',
);
$fullResponse .= array_find($response->content, static fn ($block): bool => $block->type === 'text')?->text ?? '';
if ($response->stopReason !== 'max_tokens') {
break;
}
// Continúa desde donde se quedó
$messages = [
['role' => 'user', 'content' => $prompt],
['role' => 'assistant', 'content' => $fullResponse],
['role' => 'user', 'content' => 'Please continue from where you left off.'],
];
}
return $fullResponse;
}
```
```ruby Ruby
def get_complete_response(client, prompt, max_attempts: 3)
messages = [{ role: "user", content: prompt }]
full_response = +""
max_attempts.times do
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
messages: messages
)
full_response << response.content.find { it.type == :text }&.text.to_s
break unless response.stop_reason == :max_tokens
# Continúa desde donde se quedó
messages = [
{ role: "user", content: prompt },
{ role: "assistant", content: full_response },
{ role: "user", content: "Please continue from where you left off." }
]
end
full_response
end
```
### Obtener el máximo de tokens sin conocer el tamaño de la entrada
Con la razón de detención `model_context_window_exceeded`, puedes solicitar el máximo posible de tokens sin calcular el tamaño de la entrada:
```python Python
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":
# Se obtuvo el máximo de tokens posible según el tamaño de la entrada
print(
f"Generated {response.usage.output_tokens} tokens (context limit reached)"
)
case "max_tokens":
# Se obtuvo exactamente la cantidad de tokens solicitada
print(
f"Generated {response.usage.output_tokens} tokens (max_tokens reached)"
)
case _:
# Finalización natural
print(
f"Generated {response.usage.output_tokens} tokens (natural completion)"
)
return next((block.text for block in response.content if block.type == "text"), "")
```
```typescript TypeScript
async function getMaxPossibleTokens(client: Anthropic, prompt: string): Promise {
const response = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 20000,
messages: [{ role: "user", content: prompt }]
});
const tokens = response.usage.output_tokens;
switch (response.stop_reason) {
case "model_context_window_exceeded":
// Se obtuvo el máximo de tokens posible según el tamaño de la entrada
console.log(`Generated ${tokens} tokens (context limit reached)`);
break;
case "max_tokens":
// Se obtuvo exactamente la cantidad de tokens solicitada
console.log(`Generated ${tokens} tokens (max_tokens reached)`);
break;
default:
// Finalización natural
console.log(`Generated ${tokens} tokens (natural completion)`);
}
const textBlock = response.content.find(
(block): block is Anthropic.Beta.BetaTextBlock => block.type === "text"
);
return textBlock?.text ?? "";
}
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Model = Anthropic.Models.Messages.Model;
static async Task GetMaxPossibleTokens(AnthropicClient client, string prompt)
{
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 20000,
Messages = [new() { Role = Role.User, Content = prompt }]
});
var tokens = response.Usage.OutputTokens;
var reason = response.StopReason?.Value();
if (reason == BetaStopReason.ModelContextWindowExceeded)
{
// Se obtuvo el máximo de tokens posible según el tamaño de la entrada
Console.WriteLine($"Generated {tokens} tokens (context limit reached)");
}
else if (reason == BetaStopReason.MaxTokens)
{
// Se obtuvo exactamente la cantidad de tokens solicitada
Console.WriteLine($"Generated {tokens} tokens (max_tokens reached)");
}
else
{
// Finalización natural
Console.WriteLine($"Generated {tokens} tokens (natural completion)");
}
return response.Content.Select(b => b.Value).OfType().FirstOrDefault()?.Text ?? "";
}
```
```go Go
func getMaxPossibleTokens(client anthropic.Client, prompt string) (string, error) {
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 20000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(prompt)),
},
})
if err != nil {
return "", err
}
tokens := response.Usage.OutputTokens
switch response.StopReason {
case anthropic.BetaStopReasonModelContextWindowExceeded:
// Se obtuvo el máximo de tokens posible según el tamaño de la entrada
fmt.Printf("Generated %d tokens (context limit reached)\n", tokens)
case anthropic.BetaStopReasonMaxTokens:
// Se obtuvo exactamente la cantidad de tokens solicitada
fmt.Printf("Generated %d tokens (max_tokens reached)\n", tokens)
default:
// Finalización natural
fmt.Printf("Generated %d tokens (natural completion)\n", tokens)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
return textBlock.Text, nil
}
}
return "", nil
}
```
```java Java
import com.anthropic.models.beta.messages.BetaContentBlock;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaStopReason;
import com.anthropic.models.beta.messages.MessageCreateParams;
static String getMaxPossibleTokens(AnthropicClient client, String prompt) {
BetaMessage response = client.beta().messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(20000L)
.addUserMessage(prompt)
.build()
);
long tokens = response.usage().outputTokens();
BetaStopReason reason = response.stopReason().orElse(BetaStopReason.END_TURN);
if (reason.equals(BetaStopReason.MODEL_CONTEXT_WINDOW_EXCEEDED)) {
// Se obtuvo el máximo de tokens posible según el tamaño de la entrada
IO.println("Generated " + tokens + " tokens (context limit reached)");
} else if (reason.equals(BetaStopReason.MAX_TOKENS)) {
// Se obtuvo exactamente la cantidad de tokens solicitada
IO.println("Generated " + tokens + " tokens (max_tokens reached)");
} else {
// Finalización natural
IO.println("Generated " + tokens + " tokens (natural completion)");
}
return response.content().stream()
.filter(BetaContentBlock::isText)
.findFirst()
.map(block -> block.asText().text())
.orElse("");
}
```
```php PHP
function get_max_possible_tokens(Client $client, string $prompt): string
{
$response = $client->beta->messages->create(
maxTokens: 20000,
messages: [['role' => 'user', 'content' => $prompt]],
model: 'claude-opus-5-5',
);
$tokens = $response->usage->outputTokens;
echo match ($response->stopReason) {
// Se obtuvo el máximo de tokens posible según el tamaño de la entrada
'model_context_window_exceeded' => "Generated {$tokens} tokens (context limit reached)",
// Se obtuvo exactamente la cantidad de tokens solicitada
'max_tokens' => "Generated {$tokens} tokens (max_tokens reached)",
// Finalización natural
default => "Generated {$tokens} tokens (natural completion)",
}, PHP_EOL;
return array_find($response->content, static fn ($block): bool => $block->type === 'text')?->text ?? '';
}
```
```ruby Ruby
def get_max_possible_tokens(client, prompt)
response = client.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 20000,
messages: [{ role: "user", content: prompt }]
)
tokens = response.usage.output_tokens
case response.stop_reason
when :model_context_window_exceeded
# Se obtuvo el máximo de tokens posible según el tamaño de la entrada
puts "Generated #{tokens} tokens (context limit reached)"
when :max_tokens
# Se obtuvo exactamente la cantidad de tokens solicitada
puts "Generated #{tokens} tokens (max_tokens reached)"
else
# Finalización natural
puts "Generated #{tokens} tokens (natural completion)"
end
response.content.find { it.type == :text }.text
end
```
## Próximos pasos
Reintenta las solicitudes rechazadas en un modelo de fallback, del lado del servidor o en tu cliente.
Deja que el SDK gestione el bucle de `tool_use`, el formato de los resultados y los reintentos por ti.
Lee `stop_reason` del evento `message_delta` al usar streaming.
Maneja los errores HTTP 4xx y 5xx, que son distintos de las razones de detención.