Cómo solucionar los errores 500, 502 y 524 en las API de IA

Cómo solucionar los errores 500, 502 y 524 en las API de IA#

Los errores de las API de IA son frustrantes porque suelen aparecer en el peor momento: durante una demostración, un flujo de trabajo en producción, la ejecución de un agente de programación o una tarea automatizada de atención al cliente.

En conversaciones reales de soporte, hay tres familias de errores que aparecen una y otra vez:

• 500 — fallo del servidor o del servicio de origen;
• 502 — fallo de la puerta de enlace o respuesta no válida del servicio de origen;
• 524 — tiempo de espera agotado, a menudo debido a una solicitud de larga duración.

El error está en tratar los tres de la misma manera.

Un reintento puede resolver una solicitud. No resolverá un diseño frágil en producción.

Esta guía explica qué suelen significar estos errores, qué comprobar primero y cómo hacer que las llamadas a las API de IA sean más resilientes mediante registros, reintentos, modelos alternativos y endpoints alternativos.

Tabla rápida de errores#

Si solo te quedas con una cosa: registra el modelo, el endpoint, la hora de la solicitud, el código de error y si el streaming estaba habilitado. Sin esos datos, diagnosticar el problema se convierte en un ejercicio de conjeturas.

Qué suele significar un error 500 en una API de IA#

Un error 500 suele indicar que algo ha fallado en el servidor.

En un flujo de trabajo con una API de IA, puede deberse a lo siguiente:

• la puerta de enlace encontró un error interno;
• el proveedor del modelo de origen devolvió un fallo inesperado;
• la ruta del modelo estaba temporalmente inestable;
• el cuerpo de la solicitud desencadenó un caso límite;
• una solicitud larga o compleja falló durante el procesamiento.

Un 500 aislado suele ser temporal.

Si el 500 se repite con la misma solicitud, normalmente necesitas revisar su estructura.

Comprueba:

1. el nombre del modelo;
2. la ruta del endpoint;
3. el formato de los mensajes;
4. el esquema de llamadas a herramientas/funciones;
5. el formato de los datos de imagen/vídeo/audio;
6. el tamaño del contexto;
7. si la misma solicitud funciona con otro modelo.

Qué suele significar un error 502 en una API de IA#

Un 502 Bad Gateway significa que la puerta de enlace no recibió una respuesta válida del servicio de origen.

En las API de IA, las causas habituales incluyen:

• inestabilidad del proveedor de origen;
• sobrecarga de la ruta del modelo;
• respuesta incorrecta o incompleta del servicio de origen;
• interrupción de la red;
• fallo específico de una ruta;
• incompatibilidad entre la puerta de enlace y el proveedor para una función especial del modelo.

Si se produce un 502 una sola vez, puede bastar con reintentar.

Si se repite con un modelo, prueba uno similar.

Por ejemplo, si un modelo de razonamiento de gama alta está inestable, envía temporalmente el mismo prompt a:

• una versión cercana del modelo;
• un modelo más rápido de la misma familia;
• un proveedor diferente con capacidades similares;
• un modelo alternativo más económico para tareas no críticas.

Aquí es donde resulta útil una puerta de enlace: puedes cambiar de ruta de modelo sin reescribir la aplicación.

Qué suele significar un error 524 por tiempo de espera agotado#

Un 524 suele indicar que la conexión agotó el tiempo de espera mientras esperaba una respuesta.

Es habitual con:

• prompts muy largos;
• ventanas de contexto grandes;
• salidas previstas de gran tamaño;
• tareas de razonamiento complejas;
• trabajos de generación de imágenes o vídeos;
• solicitudes sin streaming que tardan demasiado;
• flujos de trabajo de agentes de programación que piden al modelo resolver demasiado en una sola llamada.

Soluciones inmediatas:

1. reduce el tamaño de la entrada;
2. reduce max_tokens o la longitud de la salida;
3. usa streaming para las respuestas de texto;
4. divide la tarea en pasos más pequeños;
5. elige un modelo más rápido;
6. evita pedir una salida JSON enorme en una sola respuesta.

Un tiempo de espera agotado no siempre indica una caída de la plataforma. A veces significa que la solicitud es demasiado grande o tarda demasiado para una llamada síncrona a la API.

Lista de comprobaciones inmediatas para diagnosticar problemas#

Cuando falle una solicitud a una API de IA, haz estas comprobaciones antes de cambiar toda la configuración.

Para los clientes compatibles con OpenAI que usan Crazyrouter, las URL base habituales son:

https://crazyrouter.com/v1

y:

https://cn.crazyrouter.com/v1

No añadas parámetros UTM ni cadenas de seguimiento a los endpoints de la API.

Cómo implementar una estrategia de reintentos segura#

Los reintentos ayudan, pero reintentar a ciegas puede empeorar una interrupción del servicio.

Usa una espera exponencial con variación aleatoria:

import random
import time
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CRAZYROUTER_API_KEY",
    base_url="https://crazyrouter.com/v1"
)

def call_with_retry(messages, model="gpt-5-mini", max_retries=3):
    last_error = None

    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
                timeout=60,
            )
        except Exception as exc:
            last_error = exc
            wait = (2 ** attempt) + random.random()
            time.sleep(wait)

    raise last_error

Esto es mejor que reintentar inmediatamente en un bucle sin pausas.

Ejemplo de uso de modelos alternativos ante fallos#

Una aplicación en producción no debería depender de una sola ruta de modelo para todas las tareas.

Puedes definir una lista de alternativas:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CRAZYROUTER_API_KEY",
    base_url="https://crazyrouter.com/v1"
)

MODELS = [
    "gpt-5-mini",
    "claude-sonnet-4-6",
    "gemini-2.5-flash",
]

def call_with_model_fallback(messages):
    errors = []

    for model in MODELS:
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
                timeout=60,
            )
        except Exception as exc:
            errors.append({"model": model, "error": str(exc)})

    raise RuntimeError(f"All model routes failed: {errors}")

Este patrón es especialmente útil para:

• bots de soporte;
• automatización interna;
• agentes de programación;
• flujos de procesamiento para generar resúmenes;
• flujos de trabajo de contenido por lotes;
• aplicaciones en producción con requisitos de latencia de cara al usuario.

Ejemplo de uso de endpoints alternativos ante fallos#

Si tus usuarios o servidores tienen a veces un acceso inestable a una región, puedes probar un endpoint alternativo.

from openai import OpenAI

ENDPOINTS = [
    "https://crazyrouter.com/v1",
    "https://cn.crazyrouter.com/v1",
]

API_KEY = "YOUR_CRAZYROUTER_API_KEY"

for base_url in ENDPOINTS:
    client = OpenAI(api_key=API_KEY, base_url=base_url)
    try:
        response = client.chat.completions.create(
            model="gpt-5-mini",
            messages=[{"role": "user", "content": "Health check"}],
            timeout=30,
        )
        print("working endpoint:", base_url)
        break
    except Exception as exc:
        print("failed endpoint:", base_url, exc)

No cambies de endpoint al azar en cada solicitud. Usa los endpoints alternativos de forma deliberada y registra qué ruta funcionó.

Qué enviar al equipo de soporte#

Si el problema persiste, el equipo de soporte podrá ayudarte mucho más rápido si incluyes la información adecuada.

Envía:

• el correo electrónico de la cuenta;
• el nombre del modelo;
• la URL base utilizada;
• la ruta del endpoint;
• la hora de la solicitud y la zona horaria;
• el código de error;
• el cuerpo del error o una captura de pantalla;
• si el streaming estaba habilitado;
• si la misma solicitud funciona con otro modelo;
• una versión simplificada del cuerpo de la solicitud sin secretos.

No envíes tu clave de API completa en canales públicos.

Cómo ayuda una puerta de enlace a mejorar la fiabilidad de las API de IA#

Una puerta de enlace de API de IA no puede hacer que todos los proveedores de origen sean perfectos.

Pero sí puede hacer que tu aplicación sea más flexible.

Con una puerta de enlace, puedes:

• cambiar de modelo sin reescribir el código del SDK;
• dirigir las tareas sencillas a modelos más económicos;
• dirigir las tareas críticas a modelos más potentes;
• añadir alternativas entre distintas familias de modelos;
• mantener una única interfaz de integración compatible con OpenAI;
• supervisar los costes y el uso de forma más centralizada.

Con Crazyrouter, los clientes compatibles con OpenAI pueden usar:

https://crazyrouter.com/v1

o, cuando sea necesario:

https://cn.crazyrouter.com/v1

Así, tu aplicación puede centrarse en la lógica de reintentos, la política de alternativas ante fallos y una buena observabilidad.

Lista de comprobaciones para producción#

Antes de depender de una API de IA en producción, aplica esta lista de comprobaciones.

Enlaces útiles#

• Guía de configuración de la URL base: https://crazyrouter.com/blog/openai-compatible-api-base-url-explained?utm_source=blog&utm_medium=article&utm_campaign=api_error_guide
• Lista de modelos: https://crazyrouter.com/models?utm_source=blog&utm_medium=article&utm_campaign=api_error_guide
• Calculadora de precios: https://crazyrouter.com/tools/pricing-calculator/?utm_source=blog&utm_medium=article&utm_campaign=api_error_guide
• Comparación de modelos: https://crazyrouter.com/tools/model-comparison/?utm_source=blog&utm_medium=article&utm_campaign=api_error_guide
• Documentación de la API: https://docs.crazyrouter.com

Preguntas frecuentes#

¿Qué significa un error 500 en una API de IA?#

Un error 500 en una API de IA suele indicar un fallo interno del servidor o del proveedor de origen. Reintenta una vez y después comprueba el modelo, el endpoint, el formato de la solicitud y si el mismo prompt funciona con otro modelo.

¿Qué significa un error 502 en una API de IA?#

Un error 502 suele indicar que la puerta de enlace no pudo obtener una respuesta válida del proveedor del modelo de origen. A menudo es temporal, pero si los errores 502 se repiten, puede ser necesario recurrir a un modelo o una ruta alternativos.

¿Qué significa un error 524 por tiempo de espera agotado?#

Un error 524 por tiempo de espera agotado suele indicar que la solicitud tardó demasiado. Reduce el tamaño del contexto, acorta la salida prevista, usa streaming, divide la tarea o elige un modelo más rápido.

¿Debo reintentar todas las solicitudes fallidas a una API de IA?#

No. Reintenta los errores temporales del servidor, de la puerta de enlace y de tiempo de espera agotado con una espera progresiva. No reintentes a ciegas los errores de autenticación, los errores de modelo no válido ni las solicitudes con un cuerpo incorrecto.

¿Cómo puedo hacer que las llamadas a una API de IA sean más fiables?#

Usa tiempos de espera explícitos, reintentos con espera progresiva, modelos alternativos, endpoints alternativos, registros de solicitudes, límites del tamaño del cuerpo de las solicitudes y supervisión de la latencia, el uso de tokens y las tasas de error.