Antes de diagnosticar errores de Llama API, confirme un punto: la vista previa pública de Llama API de Meta dejó de funcionar el 6 de julio de 2026. Si sigue llamando a la dirección antigua, lo más probable es recibir un aviso de baja o una redirección, no un 401 ni un 429. Muchos diagnósticos de "la clave expiró" o "el modelo no existe" en realidad corresponden a un endpoint que ya dejó de prestar servicio.

Hoy las llamadas a modelos Llama suelen pasar por proveedores de alojamiento externos, servicios de inferencia autohospedados o una pasarela unificada. La autenticación, la URL base, el ID de modelo, los criterios de limitación y la estructura de errores no son uniformes entre plataformas; no existe una tabla universal de errores. Este artículo separa 401, 404, 429, timeouts y errores 400 de llamadas a herramientas, y ofrece un orden de diagnóstico y código reutilizable de manejo de errores. Los modelos y precios se rigen por la página de precios del sitio.

Nota: Llama es una marca de Meta Platforms, Inc. Las interfaces, códigos de error y criterios de limitación de cada proveedor pueden cambiar con las versiones; este artículo toma como ejemplo la situación habitual de octubre de 2026 y se rige en última instancia por la documentación oficial de cada plataforma.

1. Primero distinga en qué capa ocurre el error

Un mismo fallo puede tener causas completamente distintas. Revise primero el código de estado, el tipo de error y el ID de solicitud; después decida si cambia configuración, código o plataforma.

Síntoma Significado habitual Revisar primero
Aviso de baja o redirección La solicitud llega a un endpoint retirado Dominio y URL base
401 Fallo de autenticación Clave, encabezados, correspondencia de plataforma
404 Ruta o modelo inexistente URL base, ruta, ID de modelo
429 Límite de velocidad o cuota Concurrencia, clave compartida, política de reintentos
400 con mención de context length Contexto excedido Longitud de entrada, reserva de salida
400 con mención de tool o JSON Formato de herramienta inválido Esquema de parámetros, análisis y reintento
Timeout Tiempo de conexión, primer token o lectura Red, longitud de entrada, configuración de timeout
5xx Error del servicio upstream Reintento con retroceso, página de estado

El registro debe incluir al menos hora, plataforma, URL base, ID de modelo, código de estado, tipo de error, duración e ID de solicitud; no registre la clave completa ni el texto original del usuario.

2. 401: la clave y la plataforma deben corresponder

Un 401 indica que la identidad no se validó y normalmente no tiene relación con la capacidad del modelo ni con el saldo. Llama no tiene una clave universal: la clave de la antigua plataforma de Meta no sirve en un proveedor externo, ni al contrario. Otras causas habituales:

  • El encabezado no usa Authorization: Bearer <key>, o tiene errores de escritura o mayúsculas.
  • La clave trae espacios, saltos de línea o comillas delante o detrás, algo frecuente al copiar desde una ventana de chat.
  • La variable de entorno no se cargó realmente y el entorno desplegado conserva el valor antiguo.
  • La clave fue eliminada, rotada o desactivada, y la tarea programada sigue usando el valor viejo.
  • Un proxy inverso o una pasarela sobrescribe o descarta el encabezado Authorization.
  • Hay un problema de estado de cuenta o permisos regionales: la clave es válida pero no puede llamar a ese modelo.

Haga primero una solicitud mínima con curl y confirme que clave, URL base e ID de modelo pasan al mismo tiempo. Si sigue el 401, pruebe con una clave nueva para separar el problema de la clave, del proxy y de la pasarela. No fije la clave en el cliente ni permita que el frontend la tenga directamente.

3. 404: URL base, nombre de modelo y endpoints retirados

Un 404 normalmente no significa "el modelo está roto", sino que la solicitud llegó a una dirección o a un modelo inexistente. En 2026, el caso más común es que la dirección propia de Meta de los tutoriales antiguos ya no existe y la solicitud devuelve 404 o un aviso de baja. Otras causas:

  • La URL base corresponde a otra plataforma, o tiene /v1 de más o de menos.
  • El SDK añade /chat/completions automáticamente y la ruta escrita a mano lo añade otra vez.
  • El ID de modelo usa el nombre de la plataforma antigua y el nuevo proveedor no lo reconoce.
  • El ID necesita prefijo o sufijo de versión, o las mayúsculas y los guiones no coinciden.
  • El modelo no está disponible en la región de destino o fue retirado por la plataforma.
  • Las reglas de reescritura del proxy inverso dañan la ruta.

Los nombres de modelo varían mucho entre plataformas; conviene mantener una tabla de mapeo en la configuración en lugar de dispersar nombres en el código. Al cambiar, modifique solo el mapeo y la URL base. Ante un 404, revise primero el catálogo de modelos y luego la ruta; no intente resolverlo con reintentos.

4. 429: límites, cuotas y tormenta de reintentos

Un 429 indica que la solicitud superó el límite de velocidad, de concurrencia o de cuota. Los criterios varían entre proveedores y pueden basarse en solicitudes por minuto, tokens por minuto, cuota diaria o nivel de cuenta, según la documentación de la plataforma. Escenarios habituales:

  • Varios servicios comparten una clave y compiten por la misma cuota.
  • Las tareas por lotes arrancan a la misma hora y generan un pico de tráfico.
  • Los reintentos no tienen retroceso y cuanto más fallan más se envían, formando una tormenta.
  • Un contexto largo o una salida extensa consumen más tokens y reducen el espacio de concurrencia.
  • La cuota gratuita o de prueba se agotó y la plataforma sigue devolviendo 429 o un error similar.

Orden de tratamiento: baje primero la concurrencia, añada después retroceso exponencial y jitter, y solo al final considere dividir claves o ampliar la cuota. Dividir claves solo alivia conflictos de compartición, no resuelve un exceso total. El monitoreo debe medir la proporción de 429 por separado y desglosarla por plataforma, modelo y proyecto; de lo contrario es difícil saber qué consumidor agotó la cuota.

5. Timeouts: conexión, primer token, lectura y streaming

Un timeout no equivale a servicio no disponible; primero localice en qué tramo se atasca:

  • Timeout de conexión: DNS, salida o proxy inalcanzable; la solicitud todavía no llegó a la plataforma.
  • Primer token lento: entrada demasiado larga, cola en la plataforma o modelo con alta carga.
  • Timeout de lectura: salida demasiado larga, razonamiento prolongado o conexión cortada por un dispositivo intermedio.
  • Interrupción de streaming: fluctuación de red o corte del proxy; solo se recibió una parte del contenido.
  • Timeouts simultáneos en todo el sitio: fallo de la salida local o del upstream; revise primero la página de estado.

Los timeouts de conexión y de lectura deben configurarse por separado. Un valor único demasiado alto retiene el grupo de hilos durante una falla; uno demasiado bajo mata tareas largas normales. En streaming, registre el contenido recibido y la posición de la interrupción, admita reconexión y deduplicación, y no guarde contenido parcial en la base de datos.

6. 400: contexto excedido y formato de llamadas a herramientas

El 400 cubre un rango amplio; revise primero las palabras clave del mensaje. Si menciona context length, maximum tokens o input too long, suele ser contexto excedido: entrada más reserva de salida supera el límite del modelo. La solución es contar tokens, truncar el historial, comprimir el contenido recuperado o cambiar a un modelo con más contexto. No aumente solo max_tokens, porque reduce el espacio de entrada.

Si menciona tool, function, arguments o JSON, suele ser formato inválido de llamada a herramienta: JSON que no se puede analizar, campos obligatorios ausentes, tipos de parámetro incorrectos o un nombre de herramienta inexistente. Principios de tratamiento:

  1. Valide los parámetros con JSON Schema; no concatene cadenas directamente.
  2. Si el análisis falla, devuelva al modelo el mensaje de error y el formato esperado para que corrija una vez.
  3. Limite el número de correcciones para evitar bucles infinitos.
  4. Registre la respuesta original para determinar si el problema es del modelo o del prompt.
  5. Aplique doble validación a herramientas de alto riesgo; no confíe solo porque el modelo diga "ejecutado".

7. Código reutilizable de manejo de errores

El ejemplo usa la interfaz compatible con OpenAI, lee la URL base y el ID de modelo de variables de entorno y desactiva los reintentos automáticos del SDK para evitar que se sumen al retroceso personalizado.

import os
import random
import time
import logging
from openai import (
    OpenAI, AuthenticationError, NotFoundError, RateLimitError,
    BadRequestError, APITimeoutError, APIStatusError,
)

logging.basicConfig(level=logging.INFO)
client = OpenAI(
    api_key=os.environ["LLAMA_HOST_API_KEY"],
    base_url=os.environ["LLAMA_HOST_BASE_URL"],  # Dirección compatible de cada proveedor
    max_retries=0,
    timeout=90,
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model=os.environ["LLAMA_MODEL_ID"],
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content
        except AuthenticationError:
            raise  # La clave no corresponde a la plataforma; reintentar no ayuda
        except NotFoundError as exc:
            logging.error("Revise la URL base y el ID de modelo: %s", exc.request_id)
            raise
        except BadRequestError as exc:
            logging.error("Hay un problema de parámetros, contexto o formato de herramienta: %s", exc.request_id)
            raise
        except (RateLimitError, APITimeoutError) as exc:
            wait = min(2 ** attempt, 20) + random.random()
            logging.warning("Fallo número %s; reintento en %.1f segundos: %s",
                            attempt + 1, wait, exc.request_id)
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                logging.warning("Upstream %s; reintento en %.1f segundos", exc.status_code, wait)
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Se agotaron los reintentos; revise los límites y la configuración de timeout")

El reintento solo sirve para errores transitorios. Un 401, un 404 y la mayoría de los 400 no mejoran al reintentar; solo multiplican registros y factura. En operaciones con efectos secundarios, use una clave de idempotencia o una verificación de estado para confirmar si ya se ejecutó.

8. Registros, monitoreo y orden de diagnóstico

Diagnostique en este orden para no cambiar de modelo de inmediato:

  1. Registre código de estado, tipo de error, ID de solicitud, plataforma, URL base, ID de modelo y hora.
  2. Si la solicitud llega a la antigua dirección propia de Llama API, complete primero la migración.
  3. Para 401, revise clave, encabezados, variables de entorno y correspondencia de plataforma.
  4. Para 404, revise URL base, ruta /v1 y catálogo actual de modelos.
  5. Para 429, revise concurrencia, claves compartidas, política de reintentos y horas pico.
  6. Para timeouts, revise DNS, proxy, longitud de entrada, tiempo al primer token y timeout de lectura.
  7. Para 400, revise longitud de contexto, soporte de parámetros y esquema de herramientas.
  8. Para 5xx, reintente con retroceso; si persiste, contacte a la plataforma con el ID de solicitud.

El monitoreo debe contar al menos por hora los 401, 404, 429, timeouts y 5xx, desglosados por plataforma y modelo. Cuando la tasa de error sube de golpe, revise primero si se concentra en un proyecto, una clave o un modelo, y luego decida si baja la concurrencia, cambia de canal o revierte.

Preguntas frecuentes

¿Un 401 de Llama API significa que la clave expiró?

No necesariamente. Lo más común es que la clave no corresponda a la plataforma, por ejemplo, usar una clave de la antigua plataforma de Meta en un proveedor externo o al contrario. Confirme el encabezado, la variable de entorno y la plataforma de origen de la clave, y vuelva a probar con una solicitud mínima.

¿Por qué aparece un 404 al cambiar de proveedor?

Porque cambió el ID de modelo. Cada plataforma usa nombres, prefijos, sufijos de versión y regiones disponibles distintos, y el nombre antiguo suele no existir en la nueva. Cree una tabla de mapeo y rija la decisión por el catálogo del nuevo proveedor.

¿Conviene reintentar de inmediato ante un 429?

No haga reintentos densos inmediatos. Baje primero la concurrencia, aplique retroceso exponencial con jitter y fije un límite. Un 429 persistente indica que la cuota total no alcanza; hay que dividir claves, escalonar horarios o ajustar la cuota.

¿Se puede reintentar un timeout sin límite?

No. Los reintentos necesitan límite, retroceso y alertas. Un timeout también puede significar que la solicitud ya se ejecutó en el upstream; en operaciones con efectos secundarios, confirme primero el estado y luego decida si reenvía.

¿Qué hacer si falla el análisis JSON de los parámetros de una herramienta?

Valide primero con JSON Schema y conserve la respuesta original; después devuelva al modelo el mensaje de error y el formato esperado para que corrija una vez, con un límite de intentos. Las herramientas de alto riesgo requieren doble validación; no acepte la afirmación de éxito del modelo sin comprobarla.

Siguiente paso

Cree primero una clave de prueba en ZSQH AI Gateway, ensaye una vez cada caso de 401, 404, 429, timeout y fallo de llamada a herramienta, y luego conecte el monitoreo de producción. La disponibilidad y los precios de los modelos se rigen por la página de precios.

Lecturas relacionadas: