Ir al contenido principal
Español— Elegir un idioma
Menú

Limitaciones del modo JSON y gestión de errores

Lección 6 de 12 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Válido no significa correcto
  2. Sin garantías de esquema
  3. Validación obligatoria en el cliente
  4. Tres fallos que encontrarás
  5. Reintento con retroalimentación
  6. La señal para cambiar de enfoque
  7. Puntos clave

Válido no significa correcto

El modo JSON garantiza que el JSON sea sintácticamente válido, no que sea semánticamente correcto. Esta distinción puede parecer sutil durante el desarrollo, pero se vuelve crítica en producción. Un JSON que se analiza sin errores pero que contiene claves inesperadas genera exactamente ese tipo de error que cuesta días localizar, porque no se lanza ninguna excepción en el momento en que ocurre el problema.

Sin garantías de esquema

El mecanismo no sabe nada sobre tu esquema: nunca ha visto la estructura que espera tu código. El modelo podría omitir un campo que necesitas, añadir uno que no solicitaste, renombrar una clave —firstName en lugar de first_name— o cambiar un tipo devolviendo "42" como cadena cuando esperabas el número 42. Nada de esto invalida el JSON.

# Esperas esto:
# {"name": "Alice", "age": 30, "city": "Paris"}

# Pero podrías recibir:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}

El JSON es válido, pero la estructura no coincide con lo que espera tu código. Esta es la diferencia fundamental respecto a las salidas estructuradas personalizadas.

Validación obligatoria en el cliente

Dado que el esquema no está garantizado, la validación recae sobre ti. El patrón mínimo hace tres cosas en orden: intenta el análisis, verifica que la raíz sea un objeto (no una lista ni un escalar) y luego comprueba las claves requeridas. Cada fallo lanza un ValueError con un mensaje que puedes usar en tus registros.

import json
from typing import Optional

def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
    """Analiza JSON y verifica las claves requeridas."""
    try:
        data = json.loads(raw_content)
    except json.JSONDecodeError as e:
        raise ValueError(f"JSON no válido: {e}")

    if not isinstance(data, dict):
        raise ValueError(f"Se esperaba un objeto JSON, se recibió {type(data).__name__}")

    missing = [k for k in required_keys if k not in data]
    if missing:
        raise ValueError(f"Faltan claves: {missing}")

    return data

# Uso
try:
    result = parse_and_validate(
        response.choices[0].message.content,
        required_keys=["name", "category", "priority"]
    )
    process_ticket(result)
except ValueError as e:
    log_error(f"Salida no válida: {e}")
    fallback_processing(raw_content)

La versión en TypeScript da un paso más al verificar, además de la presencia de claves, que la categoría devuelta pertenezca a la lista permitida. Esta es la comprobación que falta con más frecuencia y la que evita que un ticket clasificado como "urgent_billing" se cuele silenciosamente en tu enrutamiento.

interface TicketClassification {
  category: string;
  priority: string;
  sentiment: string;
  summary: string;
}

function validateTicket(raw: string): TicketClassification {
  const data = JSON.parse(raw);

  const requiredKeys = ["category", "priority", "sentiment", "summary"];
  const missing = requiredKeys.filter((k) => !(k in data));

  if (missing.length > 0) {
    throw new Error(`Faltan claves: ${missing.join(", ")}`);
  }

  const validCategories = ["billing", "account", "technical", "feature_request", "other"];
  if (!validCategories.includes(data.category)) {
    throw new Error(`Categoría no válida: ${data.category}`);
  }

  return data as TicketClassification;
}

Tres fallos que encontrarás

El primero es el JSON truncado. Si la respuesta alcanza el límite de max_tokens, se corta a mitad de flujo y se vuelve inválida: la llave de cierre nunca llega. Puedes detectar el síntoma antes incluso de analizar: finish_reason es igual a "length" en lugar de "stop".

response = client.chat.complete(
    model="mistral-small-latest",
    messages=messages,
    response_format={"type": "json_object"},
    max_tokens=50  # Demasiado pequeño para un JSON completo
)

# response.choices[0].finish_reason será "length" en lugar de "stop"
if response.choices[0].finish_reason == "length":
    print("Advertencia: Respuesta truncada, aumenta max_tokens")

Comprueba siempre finish_reason: si es igual a "length", la respuesta está incompleta, independientemente de lo que diga el resto del contenido.

El segundo fallo tiene que ver con los tipos. Una edad puede llegar como cadena, un precio como entero cuando esperas un flotante. En lugar de confiar en la salida, envuelve el acceso en una función auxiliar que intente la conversión y recurra a un valor por defecto si falla.

def safe_get_int(data: dict, key: str, default: int = 0) -> int:
    """Extrae un entero, con conversión si es necesario."""
    value = data.get(key)
    if value is None:
        return default
    if isinstance(value, int):
        return value
    if isinstance(value, float):
        return int(value)
    if isinstance(value, str):
        try:
            return int(value)
        except ValueError:
            return default
    return default

# Uso
age = safe_get_int(data, "age", default=0)

El tercero es el renombrado de claves. Con un prompt en francés, el modelo podría cambiar fácilmente phone por telephone, o name por nom. Un mapeo de sinónimos absorbe estas variaciones sin obligarte a reintentar la llamada.

def normalize_keys(data: dict, key_mapping: dict) -> dict:
    """Normaliza claves usando un mapeo de sinónimos."""
    normalized = {}
    for standard_key, aliases in key_mapping.items():
        for alias in aliases:
            if alias in data:
                normalized[standard_key] = data[alias]
                break
    return normalized

# Mapeo de sinónimos
mapping = {
    "name": ["name", "nom", "full_name", "fullName"],
    "email": ["email", "mail", "e-mail", "emailAddress"],
    "phone": ["phone", "telephone", "tel", "phoneNumber"],
}

normalized = normalize_keys(raw_data, mapping)

Reintento con retroalimentación

Cuando la validación falla a pesar de tus mejores esfuerzos, la mejor respuesta no es reintentar exactamente la misma llamada: consiste en decirle al modelo qué ha ido mal. Al devolver su propia respuesta a la conversación junto con el mensaje de error, le das el contexto necesario para autocorregirse, normalmente en el segundo intento.

import json

def call_with_retry(client, messages, max_retries=3):
    """Llamada con reintento y retroalimentación de errores."""
    for attempt in range(max_retries):
        response = client.chat.complete(
            model="mistral-large-latest",
            messages=messages,
            response_format={"type": "json_object"},
            temperature=0
        )

        raw = response.choices[0].message.content
        try:
            data = json.loads(raw)
            validate_schema(data)  # Tu función de validación
            return data
        except (json.JSONDecodeError, ValueError) as e:
            if attempt < max_retries - 1:
                # Añade retroalimentación de error al contexto
                messages.append({"role": "assistant", "content": raw})
                messages.append({
                    "role": "user",
                    "content": f"Tu respuesta no es válida: {e}. Corrígela y devuelve un JSON válido."
                })
            else:
                raise RuntimeError(f"Fallo tras {max_retries} intentos: {e}")

La señal para cambiar de enfoque

Si te ves escribiendo código de validación extenso, es una señal clara de que es hora de migrar a salidas estructuradas personalizadas. Tres umbrales típicos lo confirman: más allá de cinco campos que validar, la función de control se vuelve más larga que la propia llamada; una vez que los tipos se complican con listas anidadas o enumeraciones, la validación manual se vuelve inseparable de los errores que introduce; y para cualquier canal de producción crítico, delegar las restricciones al esquema es simplemente más seguro que reconstruirlas a mano.

Puntos clave

  • El modo JSON garantiza un JSON válido, no un esquema válido
  • Valida siempre la salida en el cliente: comprueba claves requeridas, tipos correctos y valores dentro de los límites
  • Comprueba finish_reason para detectar respuestas truncadas
  • Implementa un mecanismo de reintento con retroalimentación de errores
  • Si la validación se complica, migra a salidas estructuradas personalizadas