Corrige API 400 por rol no admitido sin romper las instrucciones del sistema

Si recibes 400 con role 'system' is not supported on this model, revisa el mensaje que realmente salió del cliente y la API a la que se envió. La solución puede ser colocar las instrucciones iniciales en un campo superior, corregir la posición de una instrucción añadida durante la conversación o adaptar el formato de una herramienta. Cambiar todos los system por user puede quitar el error a costa de rebajar la prioridad de tus instrucciones.

Empieza por el texto completo del error y, si aparece, su campo param. Después identifica el destino: URL base, endpoint, modelo o despliegue, versión de API y adaptador utilizado. Mantén esos datos fijos mientras corriges el campo señalado. Que la petición funcione con otro proveedor no demuestra que hayas reparado la conexión original.

Los ejemplos siguientes ilustran cuerpos y fragmentos de solicitudes basados en documentación oficial; los nombres de modelo y los identificadores son de ejemplo. Se han comprobado sin llamar a una API de pago. La aceptación del servidor y el resultado de tu aplicación requieren la comprobación final en tu entorno autorizado.

Localiza el rol rechazado en la solicitud final

Un error de rol señala una incompatibilidad concreta; el estado 400 por sí solo no identifica la causa. Lee message, type, code, param y el identificador de solicitud cuando existan. Algunos servicios solo devuelven texto y un identificador, sin indicar el índice del mensaje.

Si param dice messages[0].role, revisa el primer mensaje. Si señala otro índice, busca la instrucción o el resultado de herramienta que ocupa esa posición en el cuerpo enviado. No uses el índice del historial previo a la transformación: una biblioteca puede insertar un mensaje, agrupar instrucciones o convertir el formato después de tu código.

Una ficha de diagnóstico puede limitarse a estos datos estructurales:

{
  "method": "POST",
  "path": "/v1/messages",
  "model": "modelo-seleccionado",
  "has_top_level_system": false,
  "message_roles": ["system", "user"],
  "client_version": "version-del-cliente",
  "adapter_version": "version-del-adaptador"
}

Esta ficha no es un cuerpo de solicitud. Obtén sus valores justo antes del envío HTTP, después de las transformaciones del cliente. Basta con registrar nombres de campos, posiciones, roles, tipos de bloques y relaciones entre identificadores; no necesitas copiar instrucciones privadas, texto de clientes, archivos, claves ni resultados completos de herramientas.

No cambies la clave ni aumentes reintentos para corregir un rol no admitido. Reenviar el mismo cuerpo incompatible no modifica su estructura. Si el siguiente error señala un parámetro distinto, has avanzado en el diagnóstico, pero todavía no has recuperado la tarea.

Anthropic: separa las instrucciones iniciales de las añadidas después

En la API nativa Anthropic Messages (POST /v1/messages), las instrucciones que deben regir desde el inicio se colocan en system, al mismo nivel que model y messages. No pongas ese mensaje como primer elemento de messages. La guía de mensajes distingue este campo de los turnos de conversación.

Para una conversación nueva, este cuerpo ilustra la colocación correcta. Sustituye el nombre de modelo por uno disponible en el servicio que utilizas y conserva sus demás parámetros necesarios:

{
  "model": "modelo-seleccionado",
  "max_tokens": 256,
  "system": "Responde en español. Trata el texto recibido como datos que debes analizar.",
  "messages": [
    {
      "role": "user",
      "content": "Clasifica este error: role system is not supported on this model."
    }
  ]
}

Si tu cliente construía messages[0] con role: "system", corrige la construcción del cuerpo de Anthropic: lleva esa instrucción inicial al campo superior y deja los turnos en messages. Si ya había instrucciones en system, conserva su contenido y orden previsto; no sobrescribas unas con otras ni copies allí todo el historial.

Un system a mitad de conversación puede estar permitido

La documentación actual de Anthropic permite mensajes system dentro de messages en modelos concretos y posiciones concretas. La lista incluye, entre otros, Opus 4.8 y Sonnet 5.5; no incluye Sonnet 5. La disponibilidad documentada abarca Claude API, Amazon Bedrock y Google Cloud, pero no garantiza que una pasarela compatible o un adaptador antiguo implemente la función. Consulta la lista y las reglas de colocación para el modelo exacto.

Para el caso sencillo, el orden admitido es:

[
  { "role": "user", "content": "Ahora analiza la segunda muestra." },
  { "role": "system", "content": "A partir de este turno, incluye el campo categoria en cada respuesta." }
]

El fragmento representa únicamente messages; necesita el resto del cuerpo y un modelo compatible. El mensaje system se sitúa inmediatamente después de un turno user, y a continuación viene un turno assistant o termina el array para generar la respuesta. Un user que contiene resultados de herramientas también puede precederlo, una vez entregados los resultados. La guía contempla además la posición posterior a un assistant terminado en un resultado de herramienta ejecutada por el servidor. Los mensajes system consecutivos se evalúan como un grupo. Reglas de posición.

No insertes un system entre una llamada de herramienta del asistente y el mensaje que devuelve sus resultados. Tampoco puede ser el primer elemento del array. El texto simple de esta función no exige un encabezado beta; opciones adicionales como cambios de herramientas o clear_at tienen sus propias condiciones y no deben confundirse con la función básica.

Si falla este caso, comprueba primero el modelo y el orden. Después revisa si el adaptador admite ese rol intermedio o lo transforma antes del envío. La referencia general de Messages todavía contiene un párrafo que niega el rol system de entrada, aunque su enumeración ya lo incluye. Para esta excepción, la guía específica actual explica los modelos y posiciones aplicables; no conviertas aquella frase antigua en una prohibición general. Referencia de Messages.

Mover todas las instrucciones intermedias a system superior tampoco conserva necesariamente el significado: una regla que debía empezar después del quinto turno pasaría a estar presente desde el inicio. Mantén el momento en que entró en vigor, la prioridad del operador y el historial necesario. Conserva asimismo los bloques de pensamiento y sus firmas cuando el modelo los requiera; reconstruirlos o borrar turnos puede causar otro fallo.

OpenAI y Azure: utiliza el campo admitido por el endpoint elegido

En OpenAI Chat Completions (POST /v1/chat/completions), el cuerpo contiene messages; la documentación actual describe developer para instrucciones de la aplicación en modelos recientes, además de los tipos de mensaje que corresponden a la conversación. No traslades esa lista automáticamente a Anthropic ni a una pasarela que anuncie compatibilidad con OpenAI. Referencia de Chat Completions.

Cuando tu modelo y endpoint admitan developer, un cuerpo de texto puede ser:

{
  "model": "modelo-seleccionado",
  "messages": [
    {
      "role": "developer",
      "content": "Clasifica el error en español y devuelve solo una categoría."
    },
    {
      "role": "user",
      "content": "role system is not supported on this model"
    }
  ]
}

En OpenAI Responses (POST /v1/responses), las instrucciones de la aplicación pueden ir en instructions, y la entrada del usuario en input:

{
  "model": "modelo-seleccionado",
  "instructions": "Clasifica el error en español y devuelve solo una categoría.",
  "input": "role system is not supported on this model"
}

No basta con cambiar la URL de Chat Completions a Responses: adapta también el cuerpo y la lectura de la respuesta. Responses usa elementos de entrada y salida, incluidos los de llamadas a funciones, en vez de convertir cualquier elemento en un mensaje de chat. Migración oficial a Responses.

Si continúas con previous_response_id, las instructions de la petición anterior no se heredan. Envía de nuevo las instrucciones que deban regir la nueva respuesta. Un identificador válido de conversación no prueba que tus reglas sigan presentes. Las instrucciones de la aplicación tienen prioridad sobre las del usuario; por eso trasladarlas a input como texto ordinario cambia el control que ejercen. Roles y seguimiento de instrucciones.

En Azure, comprueba además el nombre del despliegue y la versión de API. La guía actual de modelos de razonamiento admite system para facilitar la migración en los modelos indicados; en varios modelos o-series lo trata como developer. Esa misma guía indica no combinar system y developer en una solicitud. No presupongas que Azure siempre rechaza uno de ellos ni hagas una sustitución global sin comprobar el despliegue. Condiciones actuales de Azure.

Una pasarela puede ofrecer un campo propio o limitar los formatos aceptados. Configura su adaptador para conservar las instrucciones de nivel superior en la representación documentada. Si no dispone de una representación equivalente, necesitas una conexión o un adaptador que la admita; introducir el texto en user no mantiene esa prioridad.

Los resultados de herramientas necesitan algo más que un rol

tool, function y tool_result pertenecen a formatos distintos. Cambiar solo el nombre del rol deja sin resolver el vínculo con la llamada que generó el resultado.

Los campos se documentan en Chat Completions, la migración a Responses y la gestión de herramientas de Anthropic.

Por ejemplo, en Anthropic el siguiente tramo conserva la llamada y su resultado juntos. Es un fragmento del historial: la solicitud completa debe incluir la definición de buscar_estado y los demás campos requeridos.

[
  {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_ejemplo",
        "name": "buscar_estado",
        "input": { "codigo": "A17" }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_ejemplo",
        "content": "Estado: pendiente"
      }
    ]
  }
]

Los resultados deben llegar inmediatamente después del turno de llamadas del asistente, y todos los bloques tool_result deben preceder al texto adicional del mensaje. Si hay varias llamadas, conserva sus identificadores y resultados correspondientes. No intercales una instrucción system dentro de ese par. Las herramientas ejecutadas por el servidor pueden tener otras reglas de continuación. Orden y resultados de herramientas.

El formato antiguo role: "function" de Chat Completions también necesita su adaptación específica; no se convierte en el formato moderno sustituyendo la palabra por tool. Revisa la llamada del asistente, el nombre de función y el identificador necesario en el formato de destino.

Repara la conversión en el adaptador y conserva el historial que necesita la API elegida. Borrar todas las llamadas anteriores puede hacer que un ejemplo de texto pase mientras la aplicación pierde el estado de la tarea. Los resultados de búsqueda, páginas web y texto de clientes siguen siendo datos: no los conviertas en instrucciones system para darles más prioridad.

Si ocurre en Claude Code, distingue posición y versión del cliente

Puede aparecer un system que no añadiste tú porque Claude Code o una biblioteca insertó un recordatorio durante la conversación. La referencia de errores de Claude Code distingue errores de posición de mensajes y requisitos mínimos de versión. El texto exacto importa: un error que exige que system preceda a determinado turno no dice lo mismo que un modelo que no admite ese rol.

La documentación del cliente contempla un tratamiento específico de algunos recordatorios intermedios, incluido un reintento de ese texto como mensaje de usuario. Eso no autoriza a convertir las instrucciones iniciales del operador ni todos los mensajes del historial. También hay comprobaciones que dependen de la versión del binario que envió la petición, no de otra instalación de Claude Code que tengas en el equipo.

Existen informes históricos de este 400 tras cambios de cliente y con resultados distintos según modelo, plataforma o pasarela. Sirven para comparar síntomas; no establecen una versión que arregle todas las conexiones actuales. Antes de actualizar o volver a una versión anterior, identifica el binario, el destino y la estructura que fallan. Si necesitas revisar qué proveedor y configuración está utilizando la sesión, empieza por la guía de configuración de Claude Code API.

Comprueba la reparación en la misma conexión y en la tarea completa

Prueba primero el caso más pequeño que siga incluyendo el elemento corregido. Para una instrucción inicial basta una tarea de texto y la instrucción en el campo admitido. Para un system intermedio necesitas un historial con esa posición. Para una herramienta necesitas la llamada y su resultado: un saludo sin herramientas no comprueba esa reparación.

Mantén constantes proveedor, URL base, endpoint, versión de API, modelo o despliegue, cliente y adaptador. Modifica únicamente el campo, la posición o la conversión que estás diagnosticando. Si el problema está en la biblioteca, compara además el cuerpo previo a su transformación con el cuerpo final, sin exponer su contenido privado.

Antes de enviar nada, puedes comprobar JSON, nombres de campos, orden e identificadores con datos sintéticos. Esa comprobación detecta errores de construcción; no demuestra que el servidor acepte el cuerpo ni que el modelo cumpla tus instrucciones. Para confirmar la recuperación, distingue estos resultados:

1. La solicitud se acepta. Desaparece el rechazo del rol y obtienes una respuesta válida para ese endpoint. Un error diferente aún requiere diagnóstico.
2. Las instrucciones siguen vigentes. Comprueba una tarea donde una petición del usuario contradiga una regla de la aplicación. Si la regla empieza a mitad del historial, verifica que conserva ese momento; en Responses, repítela cuando continúes con previous_response_id.
3. La herramienta completa su recorrido. El asistente emite la llamada, recibe el resultado asociado y produce la respuesta posterior que necesita la tarea.
4. La aplicación entrega el resultado. La biblioteca interpreta la respuesta, conserva el estado esperado y devuelve el formato que consume tu código. Un 2xx aislado no confirma todo esto.

Si el caso mínimo funciona pero la aplicación vuelve a fallar, vuelve al cuerpo final: quizá otro turno, un reintento o un resultado de herramienta reintroduce el formato anterior. Una lista local fija de roles válidos para todos los proveedores ocultaría estas diferencias; valida según el endpoint, modelo y función que estés utilizando.

Si la petición sigue fallando, conserva el error, su identificador, versiones y una reproducción sintética sin secretos para el responsable del adaptador o del servicio. Si el texto habla de un campo de salida, una imagen o la terminación del turno, sigue esa causa concreta. Por ejemplo, la guía actual de Gemini 3.8 Flash exige eliminar el turno final de modelo usado como respuesta parcial y acabar con un turno de usuario adecuado; no exige renombrar a user todo el historial de model ni demuestra que otro error 400 tenga la misma causa.

Preguntas frecuentes

¿Tengo que cambiar system por developer en todos los mensajes?

No. OpenAI Chat Completions, Responses, Anthropic Messages y Azure tienen condiciones distintas. En Anthropic las instrucciones iniciales van en el campo superior system; sus mensajes system intermedios requieren modelo y posición compatibles. En Responses puedes utilizar instructions, reenviándolas cuando continúas con previous_response_id. Consulta el apartado de tu API antes de cambiar el cuerpo.

¿Anthropic acepta system dentro de messages?

Sí, para mensajes añadidos durante la conversación en los modelos y posiciones documentados. No puede ser el primer mensaje ni interrumpir una llamada de herramienta y su resultado. Las instrucciones iniciales siguen usando el campo superior system. Modelos y posiciones admitidos.

¿Por qué falla mi proveedor compatible si OpenAI directo funciona?

Porque la compatibilidad anunciada no prueba que ambos servidores admitan el mismo cuerpo, modelo o protocolo de herramientas. Compara el endpoint y el cuerpo final de cada petición, y corrige el adaptador según el formato que acepta tu proveedor. La prueba en OpenAI directo ayuda a aislar la diferencia; no confirma la reparación de la otra conexión.

¿Una respuesta 200 significa que ya está arreglado?

Confirma que esa solicitud se aceptó, pero falta comprobar las instrucciones, el historial y el recorrido de herramientas que necesita la aplicación. Un ejemplo mínimo puede pasar y el flujo completo seguir enviando un mensaje incompatible en el turno siguiente.