¿Qué ocurre cuando falla una API? Cómo investigar el error sin adivinar

Una aplicación muestra «algo salió mal», pero detrás de ese mensaje puede haber credenciales inválidas, una petición mal formada, un límite de uso, una dependencia caída o un timeout. La respuesta está en reconstruir el recorrido de la petición.

Una API permite que dos programas intercambien información mediante un contrato: rutas, métodos, parámetros, encabezados, formatos y respuestas esperadas. Cuando algo falla, el código de estado es una pista útil, pero no siempre identifica la causa completa. Un proxy puede generar el error antes de que la petición llegue a la aplicación; una aplicación puede responder correctamente a nivel HTTP y aun así devolver un error de negocio en el cuerpo.

Primero, conserva la evidencia

Antes de cambiar código o reintentar muchas veces, registra la hora, el método HTTP, la ruta, el código de estado, el tiempo transcurrido y un identificador de petición si existe. Guarda el cuerpo de error solo después de comprobar que no contiene secretos. Anota también desde dónde se hizo la llamada: navegador, backend, contenedor, red corporativa o entorno de pruebas.

Una petición mínima con curl ayuda a separar el problema de la interfaz que lo muestra:

curl -i --connect-timeout 5 --max-time 15 \
  -H "Accept: application/json" \
  https://api.example.com/v1/status

Este comando imprime encabezados y cuerpo, limita el tiempo de conexión y el tiempo total. La ruta es ficticia: un servicio real puede requerir autenticación, un método distinto o parámetros específicos. No agregues credenciales a un comando que vayas a compartir en un historial de terminal o captura.

1. Errores 400: la petición no cumple el contrato

Los estados 4xx suelen indicar que el servidor considera que hay un problema en la solicitud del cliente, aunque la interpretación exacta depende de la API.

• 400 Bad Request: la petición es inválida o no puede interpretarse. Revisa JSON mal formado, parámetros ausentes, tipos incorrectos y codificación.
• 401 Unauthorized: faltan credenciales válidas o no se aceptaron. Comprueba si el token expiró, si se envía el encabezado correcto y si corresponde al entorno.
• 403 Forbidden: el servidor entiende la petición, pero no permite la operación. Puede faltar un permiso, un rol o una política de acceso.
• 404 Not Found: la ruta o el recurso no existe para esa petición. Verifica versión de API, prefijo, identificador y método; algunas API ocultan recursos no autorizados con un 404.
• 405 Method Not Allowed: la ruta existe, pero no admite ese método. Comprueba si corresponde GET, POST, PATCH o DELETE.
• 422 Unprocessable Content: la sintaxis pudo ser válida, pero los datos no cumplen las reglas de validación definidas por el servicio.

La forma más rápida de avanzar es comparar la petición real con la documentación: URL completa, método, encabezados obligatorios, esquema del cuerpo y permisos requeridos. Evita «arreglar» el problema probando credenciales al azar; utiliza una credencial de prueba autorizada y confirma qué alcance tiene.

2. El error 429: demasiadas solicitudes

429 Too Many Requests indica que se ha superado un límite de solicitudes según la política del servicio. Algunos proveedores incluyen encabezados como Retry-After o encabezados propios para explicar cuándo volver a intentarlo.

Respeta el tiempo indicado por el servidor. Si no se especifica, aplica una política de reintentos limitada con espera creciente (backoff exponencial) y algo de variación aleatoria (jitter). Reintentar en un bucle inmediato puede agravar la saturación y hacer que el límite se mantenga activo.

# Ejemplo conceptual: inspecciona el estado y los encabezados
curl -sS -D - -o /tmp/api-response.txt \
  https://api.example.com/v1/resource

El archivo de salida es solo ilustrativo y podría contener datos sensibles; elimínalo o sanitízalo cuando termines. En producción, revisa también si varias instancias de tu aplicación comparten una cuota, si hay solicitudes duplicadas y si puedes cachear respuestas que no cambian con frecuencia.

3. Los errores 500, 502, 503 y 504 no son lo mismo

• 500 Internal Server Error: la aplicación o el servidor encontró una condición inesperada. Si administras el servicio, correlaciona la hora y el identificador de petición con los registros del backend.
• 502 Bad Gateway: un proxy o gateway recibió una respuesta inválida de otro componente, o no pudo utilizarla correctamente.
• 503 Service Unavailable: el servicio no puede atender temporalmente la petición, por ejemplo por mantenimiento o saturación.
• 504 Gateway Timeout: un gateway no recibió a tiempo la respuesta de un componente upstream.

Estos códigos pueden generarse en distintas capas: CDN, balanceador, gateway, servidor de aplicaciones o dependencia externa. Por eso no basta con ver un 502 y concluir que «la API está caída». Compara el identificador de petición y los registros disponibles en cada capa; si no administras el servicio, conserva la hora, el código y el identificador para el equipo responsable.

4. Timeout: no significa necesariamente que el servidor esté caído

Un timeout solo indica que una operación no terminó dentro del límite de tiempo configurado. Puede ocurrir durante la resolución DNS, el establecimiento de la conexión, la negociación TLS, la espera de la respuesta o una operación interna de la aplicación. Una API lenta también puede ser consecuencia de una dependencia que tarda en responder.

Distingue el timeout de conexión del timeout total. El primero limita cuánto esperas para establecer la conexión; el segundo limita la operación completa. Ajustarlos sin medir puede ocultar una degradación o mantener recursos ocupados durante demasiado tiempo. Compara latencia normal, percentiles de latencia, frecuencia de errores y comportamiento por endpoint.

Si una petición que crea un pago, una orden o cualquier otro efecto no recibe respuesta, no asumas que no se ejecutó. El servidor pudo completar la operación y perderse la respuesta en el camino. Antes de reintentar, consulta el estado del recurso o usa el mecanismo de idempotencia documentado por la API.

5. DNS, TCP y TLS también pueden romper una llamada

No todos los fallos de API producen un código HTTP. Si el cliente no consigue resolver el host, establecer la conexión o completar TLS, quizá nunca llegue a recibir una respuesta HTTP. En esos casos, revisa las capas de red antes de analizar el cuerpo de la respuesta.

• Error de resolución: verifica el host, la respuesta DNS y el resolver utilizado.
• Conexión rechazada o timeout: comprueba el puerto, la ruta, el cortafuegos y la disponibilidad del servicio.
• Error de certificado o TLS: revisa el nombre del host, la fecha del sistema y la cadena de certificados. No desactives la validación como solución permanente.
• La API funciona desde una máquina, pero no desde otra: compara proxy, DNS, reglas de salida, variables de entorno y configuración de certificados.

Para una secuencia de pruebas más detallada, consulta nuestra guía de diagnóstico de DNS, TCP y TLS.

6. Lee el cuerpo de error, pero no confíes ciegamente en él

Muchas API devuelven JSON con un código interno, un mensaje y detalles de validación. Ese contenido puede orientar la investigación, pero no siempre es estable ni está pensado para mostrarse directamente al usuario final. El cliente debe manejar respuestas inesperadas y evitar depender de un texto exacto que pueda cambiar entre versiones.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Uno o más campos no son válidos"
  }
}

Este JSON es un ejemplo ficticio, no el formato universal de las API. Diseña el manejo de errores según el contrato real: estado HTTP, código de aplicación, campos de validación e identificador de correlación cuando esté disponible. Nunca devuelvas trazas internas, consultas, secretos o detalles de infraestructura a clientes no autorizados.

7. Reintentos seguros: cuándo sí y cuándo no

Los reintentos ayudan con fallos transitorios, pero pueden duplicar operaciones o empeorar una sobrecarga. Antes de implementarlos, define qué errores son reintentables, cuántos intentos se permiten, cuánto esperar y cómo evitar duplicados.

• Respeta Retry-After cuando el servicio lo envíe.
• Usa backoff con un máximo de intentos y un límite total de tiempo.
• Evita reintentar automáticamente errores de validación, autenticación o permisos sin corregir la causa.
• Para operaciones con efectos secundarios, utiliza claves de idempotencia si la API las soporta y consulta su documentación.
• Registra cada intento de forma correlacionable sin escribir tokens ni cuerpos sensibles en los logs.

Un patrón de reintentos no reemplaza el control de concurrencia, los límites de cuota ni el monitoreo. Si muchas instancias reintentan a la vez, pueden crear una segunda ola de tráfico justo cuando el servicio intenta recuperarse.

Una lista de comprobación para el siguiente incidente

1. Confirma URL, método, parámetros, encabezados y formato del cuerpo.
2. Registra hora, estado HTTP, latencia e identificador de petición.
3. Comprueba si el fallo ocurre antes de recibir HTTP (DNS, conexión o TLS).
4. Interpreta el estado y el cuerpo según el contrato de esa API.
5. Compara una petición mínima desde un entorno autorizado.
6. Correlaciona los registros de cliente, gateway y aplicación si tienes acceso.
7. Reintenta solo si es seguro, con límites y esperas adecuadas.

Conclusión

Una API que falla no es una sola clase de problema. El código HTTP, la latencia, los encabezados, el cuerpo y el punto donde se interrumpe la llamada son piezas de evidencia diferentes. En vez de aumentar los timeouts o repetir la petición sin control, registra el síntoma, identifica la capa y contrasta cada hipótesis con una prueba pequeña. Ese método convierte un mensaje genérico en un diagnóstico que otra persona puede reproducir.

← Volver a todas las investigaciones