Claude Opus 5.5 API: primera solicitud y errores 400

Puedes tener una API Key válida y aun así recibir 400 Bad Request en tu primera llamada a Claude Opus 5.5. Comprueba el Model ID exacto, los campos obligatorios de Messages como max_tokens, la configuración de thinking y tool_choice. La ausencia de max_tokens es un error general de validación de Messages, no una restricción nueva de Opus 5.5; los cambios propios de la migración incluyen thinking y la selección forzada de herramientas.

Esta guía empieza con una solicitud mínima y después revisa los errores 400 en orden. Usa la referencia de Messages API para los campos obligatorios y la guía de migración de Anthropic para los cambios específicos de Opus 5.5. Ejecuta una vez la solicitud mínima para comprobar la conexión y la ruta del modelo; si falla, usa el cuerpo de error devuelto. Antes de enviar claude-opus-5-5 mediante BetterToken, comprueba el día de publicación o despliegue que el Model ID exacto figure en el catálogo actual.

1. Comprueba primero la API Key, la Base URL y el Model ID

Para la primera solicitud solo necesitas tres valores: tu propia API Key de BetterToken, la Base URL Anthropic-compatible y un Model ID disponible en ese momento.

1. Inicia sesión en BetterToken Workspace y crea una API Key en tu propia cuenta. Guárdala en un gestor de secretos o en un archivo de entorno local; no la subas a Git ni la pegues en un mensaje de soporte.
2. Abre el catálogo actual de modelos y precios y confirma que está disponible el ID exacto claude-opus-5-5. Anthropic lo define como un ID fijo sin sufijo de fecha, pero la disponibilidad y el precio en BetterToken son datos dinámicos.
3. Pasa la clave mediante una variable de entorno en vez de escribirla en el código.

Necesitas tu propia cuenta de BetterToken para crear una API Key. Crear una cuenta BetterToken

Para los pasos en la interfaz, consulta el BetterToken Quickstart.

2. No pongas /v1 en la Base URL, pero sí en la ruta HTTP directa

Usa https://bettertoken.ai como Base URL del SDK de Anthropic y https://www.bettertoken.ai/v1/messages para una solicitud Messages HTTP directa.

https://bettertoken.ai

No uses /messages como Base URL ni añadas /v1/messages dos veces cuando el SDK ya incorpora la ruta del recurso. Define los tres valores en la shell actual:

read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
export ANTHROPIC_BASE_URL="https://bettertoken.ai"
export CLAUDE_MODEL_ID="claude-opus-5-5"

Ejecuta primero solo la primera línea. El terminal esperará una entrada oculta: escribe o pega la API Key y pulsa Enter; no se mostrará ningún carácter. La clave se exporta únicamente en la shell actual y el historial guarda el comando read, no el secreto. No añadas la clave a la línea de comandos.

claude-opus-5-5 es el Model ID que Anthropic documenta para Claude Platform. Si el catálogo actual de BetterToken no muestra exactamente ese ID, detente y verifica la disponibilidad en lugar de inventar un alias.

3. Envía primero una solicitud mínima

Deja fuera tools, tool_choice y thinking en la primera prueba para que las opciones avanzadas no oculten un problema básico de conexión.

curl --fail-with-body "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d "{
    \"model\": \"$CLAUDE_MODEL_ID\",
    \"max_tokens\": 4096,
    \"messages\": [
      {\"role\": \"user\", \"content\": \"Responde solo con: pong\"}
    ]
  }"

La solicitud usa el Model ID exacto, incluye un max_tokens positivo, omite thinking y no fuerza una llamada a herramienta. El ejemplo fija max_tokens en 4096, el mismo valor que usa el ejemplo de migración de Anthropic, para dejar más margen al adaptive thinking y a la respuesta corta. Es un punto de partida de diagnóstico, no una garantía probada ni una recomendación de producción; en producción ajústalo a la respuesta esperada, al effort, al coste y a la latencia.

--fail-with-body conserva el cuerpo cuando el servidor devuelve HTTP 4xx o 5xx. Elimina la API Key, los prompts completos, la salida del modelo y otros datos sensibles antes de compartir registros.

4. No supongas que content[0] siempre contiene texto

HTTP 200 con un type de nivel superior igual a message indica que el endpoint aceptó y procesó la solicitud. En esta prueba de respuesta corta, un bloque de texto confirma que la generación terminó; adaptive thinking y el texto comparten max_tokens, por lo que una respuesta válida puede agotar el límite antes de mostrar texto.

Comprueba estas señales:

• el type de nivel superior es message y el campo model coincide con el modelo solicitado;
• cuando la prueba corta termina normalmente, stop_reason es end_turn y el array content contiene al menos un bloque cuyo type es text;
• si stop_reason es max_tokens, la respuesta es válida pero está truncada: aumenta max_tokens y repite la solicitud; si configuraste un effort alto y no necesitas razonamiento profundo, también puedes bajarlo;
• si no aparece ningún bloque de texto y stop_reason no es max_tokens, conserva la respuesta completa y diagnostica esa causa de parada antes de cambiar la Key o la Base URL; la ausencia de texto por sí sola no demuestra un fallo de conexión;
• tu parser selecciona bloques por type y no lee siempre content[0].text;
• usage incluye los Token de entrada y salida;
• BetterToken Dashboard muestra una solicitud a la hora esperada, con modelo, estado, input/output/cache Token y cargo.

La referencia oficial de Anthropic Messages API documenta la estructura, y la guía de stop_reason explica cómo tratar respuestas truncadas. El Dashboard sirve para conciliar la solicitud y el uso; no debe presentarse como almacenamiento garantizado del prompt o de la respuesta completos.

5. Revisa errores generales de Messages y cambios de Opus 5.5

La solicitud aún usa un nombre de modelo antiguo

Sustituye un ID anterior o un alias con fecha inventado por claude-opus-5-5. Anthropic lo define como un ID fijo sin sufijo de fecha. Las plataformas cloud pueden usar IDs propios; este ejemplo Anthropic-compatible de BetterToken debe emplear el ID exacto del catálogo actual de BetterToken.

Falta max_tokens

Incluye un max_tokens positivo en cada solicitud Messages. Un campo ausente es un error general de validación de Messages API, no un cambio de la migración a Opus 5.5. Es un límite estricto para toda la salida, incluido thinking y el texto final. Incluso una prueba debe dejar espacio para ambos; si stop_reason es max_tokens, aumenta el límite y repite la solicitud en vez de tratarla como un fallo de conexión.

El payload desactiva thinking o fija un presupuesto manual

La corrección más sencilla es eliminar por completo el campo thinking. Opus 5.5 usa siempre adaptive thinking. La guía de migración de Anthropic identifica estas dos formas antiguas como rechazadas con 400:

{"thinking": {"type": "disabled"}}

{"thinking": {"type": "enabled", "budget_tokens": 10000}}

Si necesitas indicar el campo, usa {"thinking": {"type": "adaptive"}}. Controla la profundidad con output_config.effort; admite low, medium, high, xhigh y max, con medium por defecto. La solicitud mínima no necesita ninguno de estos campos.

El payload fuerza tool_choice

Usa únicamente {"type": "auto"} o {"type": "none"} en tool_choice. Opus 5.5 rechaza {"type": "any"} y {"type": "tool", "name": "..."}. En un flujo con herramientas, deja que el modelo elija con auto, indica en el prompt cuándo debe usar la herramienta y valida cada esquema antes de activar strict tool use.

6. Para otros estados, lee el cuerpo antes de cambiar la configuración

Estado	Comprueba primero	Evita
400	JSON válido; model, max_tokens, messages, thinking y tool_choice	Cambiar la clave a ciegas o repetir el mismo payload inválido
401 / 403	Clave completa, cuenta o grupo correctos y Base URL correcta	Enviar la clave completa a soporte
404	Una llamada HTTP directa debe usar /v1/messages	Tratar /messages como ruta completa
429	Instrucción de espera, saldo, límites e historial	Reintentar en un bucle sin pausa

Limpia las variables antiguas de otro proveedor antes de volver a configurar la shell:

unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL
unset CLAUDE_MODEL_ID

Después de corregir un punto, repite la misma solicitud mínima. Si cambias a la vez el modelo, el endpoint, el prompt y los parámetros avanzados, será difícil saber qué resolvió el problema.

7. Separa el precio de lista de Anthropic del precio actual de BetterToken

La página de lanzamiento de Anthropic del 22 de septiembre de 2026 indicaba para Claude Platform $4 por millón de Token de entrada, $20 por millón de salida, $0.20 por cache reads y $5 por cache writes. Son los precios de plataforma publicados oficialmente por Anthropic en el lanzamiento. El precio de BetterToken es dinámico, así que consulta la página actual y verifica una solicitud pequeña con tu propio registro del Dashboard.

Los thinking Token se facturan como output Token y max_tokens incluye thinking más el texto final. Por eso, una carga migrada desde una configuración que desactivaba thinking puede tener otro perfil de salida aun con el mismo prompt. Antes de producción, revisa la página de precios actual de BetterToken y concilia una solicitud pequeña con el registro del Dashboard.

Antes de pasar a un SDK, streaming o tráfico de producción, vuelve a comprobar el Model ID, guarda la clave fuera del código, dimensiona max_tokens, procesa el contenido por tipo de bloque, evita forced tool choice y conserva un cuerpo de error anonimizado. Continúa con la BetterToken API Reference y la guía oficial de migración de Opus 5.5.