Cómo depurar errores de API REST: CORS, 401, 403, 404, 415 y timeouts

Por Sayaib SarkarActualizado el 7 min de lectura

En esta página 9 secciones

Respuesta corta: reproduce la solicitud fallida fuera de tu aplicación, lee el código de estado y el cuerpo de la respuesta antes que nada y cambia una sola cosa cada vez. La mayoría de los errores de API encajan en unos pocos patrones, y el código de estado te dice cuál. Si el navegador dice «blocked by CORS policy» pero la misma solicitud funciona en un cliente de API, el problema son las cabeceras CORS del servidor, no tu solicitud.

Esta guía repasa los errores que los desarrolladores encuentran con más frecuencia al integrar una API, qué significa realmente cada uno y cómo confirmar la causa en unos minutos desde VS Code.

Paso 1: reproduce la solicitud fuera de tu aplicación

Tu aplicación añade capas: una biblioteca HTTP, interceptores, un proxy, el navegador. Quítalas primero.

  1. En el navegador, abre DevTools → Network, haz clic con el botón derecho en la solicitud fallida y elige Copy → Copy as cURL.
  2. En VS Code, abre el cliente de API REST de DevSnip Pro y pega el comando cURL en la barra de direcciones. Se importan el método, las cabeceras y el cuerpo.
  3. Envíala. Ahora puedes cambiar una cabecera cada vez y ver el efecto al instante.

Si la solicitud funciona aquí pero falla en el navegador, ve a la sección de CORS. Si falla en ambos, el código de estado de abajo te dice dónde mirar.

Lee el código de estado y el cuerpo

Antes de cambiar el código, lee lo que devolvió el servidor. Muchas APIs explican el problema en el cuerpo de la respuesta, por ejemplo {"error": "invalid_token", "error_description": "The access token expired"}.

EstadoQué suele significarRevisa primero
400 Bad RequestEl cuerpo o los parámetros no son válidosEl cuerpo de la respuesta; los campos obligatorios; la sintaxis JSON
401 UnauthorizedNo se enviaron credenciales válidasLa cabecera Authorization; la caducidad del token
403 ForbiddenLas credenciales son válidas pero no tienen permiso para estoLos scopes o roles del token; los permisos de la clave de API
404 Not FoundURL incorrecta, o el recurso no existeLa URL base, la ruta, la barra final, la versión de la API
405 Method Not AllowedURL correcta, método incorrectoGET frente a POST; la cabecera de respuesta Allow
415 Unsupported Media TypeEl servidor no puede leer el formato del cuerpoLa cabecera Content-Type
422 Unprocessable EntityJSON válido, pero no superó la validaciónLa lista de errores por campo del cuerpo de la respuesta
429 Too Many RequestsLímite de peticiones alcanzadoLa cabecera Retry-After
5xxEl servidor fallóLos logs del servidor; si otra entrada funciona

401 Unauthorized: las credenciales no llegaron o no son válidas

  • ¿Está la cabecera? Algunos clientes HTTP descartan Authorization al seguir una redirección a otro host. Revisa la solicitud que se envió de verdad, no el código que la construye.
  • ¿El formato es correcto? La mayoría de las APIs esperan Authorization: Bearer <token> con exactamente un espacio y la palabra Bearer una sola vez. Un Bearer Bearer … duplicado es un error habitual cuando el token se guarda con su prefijo.
  • ¿Ha caducado el token? Pega un JWT en JWT Decoder & Signer de DevSnip Pro: muestra la cabecera y los claims y comprueba exp. Compara también aud (audiencia) e iss (emisor) con lo que espera la API. El decodificador se ejecuta en local, así que un token real nunca va a un sitio web.

403 Forbidden: quién eres está bien, lo que haces no

El servidor sabe quién eres, pero tu token o tu clave no tienen permiso para esta operación. Revisa los scopes o roles en los claims del token, los permisos de la clave de API y si el recurso pertenece a otra cuenta u otro tenant. Repetir la misma solicitud con un token nuevo no servirá a menos que el nuevo tenga más permisos.

Algunos servidores también devuelven 403 cuando un firewall o un WAF bloquea la solicitud (por ejemplo, porque falta User-Agent). En ese caso, el cuerpo de la respuesta suele parecer una página de error HTML en lugar de JSON.

404 Not Found y 405 Method Not Allowed

Compara la URL carácter a carácter con la documentación de la API:

  • La URL base y la versión de la API (/v1/ frente a /v2/).
  • La barra final: /users y /users/ son rutas distintas en muchos servidores.
  • Parámetros de ruta que nunca se sustituyeron, como /users/undefined o /users/{id}.

Usar variables de entorno como {{baseUrl}} para el host, en lugar de escribirlo en cada solicitud, elimina toda una familia de estos errores. Si la ruta es correcta y obtienes 405, la ruta existe pero no para ese método; la cabecera de respuesta Allow enumera los que acepta.

415 y 400: el cuerpo no es lo que el servidor espera

Un cuerpo JSON necesita Content-Type: application/json. Sin ella, muchos frameworks ni siquiera analizan el cuerpo, y tu manejador lo ve vacío. Eso aparece como un 415, o como un 400 que se queja de que faltan campos obligatorios aunque los hayas enviado.

HTTP
POST /v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>

{"name": "Ada", "role": "admin"}

Si el servidor quiere datos de formulario, envía application/x-www-form-urlencoded (los endpoints de tokens de OAuth suelen pedirlo). Para comprobar un cuerpo JSON contra el esquema de la API antes de enviarlo, usa JSON Schema Validator de DevSnip Pro: enumera cada infracción con su ruta.

CORS: «blocked by CORS policy»

CORS solo lo aplican los navegadores. curl, Postman, las aplicaciones móviles y las llamadas de servidor a servidor lo ignoran, por eso una solicitud puede funcionar en un cliente de API y fallar en tu aplicación web. La solución siempre está en el servidor: debe enviar las cabeceras Access-Control-* correctas para el origen de tu página.

Las causas habituales:

  • No hay cabecera Access-Control-Allow-Origin, o tiene otro origen. http://localhost:3000 y http://localhost:5173 son orígenes distintos.
  • Falla la solicitud preflight OPTIONS. Las solicitudes con cuerpo JSON o con cabecera Authorization provocan una preflight. Si el servidor responde con 401, 404 o 405 (a menudo porque el middleware de autenticación se ejecuta antes que el de CORS), el navegador bloquea la solicitud real.
  • Credenciales con comodín. Con cookies (credentials: 'include'), el servidor debe devolver el origen exacto y Access-Control-Allow-Credentials: true. No se permite Access-Control-Allow-Origin: *.
  • Errores sin cabeceras CORS. Si el servidor devuelve un 500 sin cabeceras CORS, el navegador informa de un error de CORS y oculta el real. Devuelve las cabeceras CORS también en las respuestas de error.

CORS Builder & Debugger de DevSnip Pro tiene tres modos para esto: pega el error de la consola para obtener la causa probable y la solución, pega las cabeceras de la respuesta para revisarlas como lo haría un navegador, o genera una configuración correcta para Express, NestJS, Next.js, Fastify, nginx o FastAPI.

Timeouts y solicitudes que nunca terminan

  • Comprueba que haya algo escuchando. Port & Network Toolkit de DevSnip Pro muestra qué puertos locales están libres: si el puerto que debería usar tu API está libre, el servidor no se está ejecutando ahí.
  • Una solicitud a localhost desde un móvil o un emulador va al propio dispositivo, no a tu equipo. Usa la dirección de tu equipo en la red local o el alias del emulador para el host.
  • Las respuestas grandes y los endpoints lentos pueden necesitar un tiempo límite mayor. En DevSnip Pro, devsnip.apiTimeout define el valor por defecto (30 segundos), un tiempo límite por solicitud lo sustituye y Cancel detiene una solicitud antes de tiempo.

Después, arréglalo en el código

Cuando una solicitud funcione en el cliente de API, genera la misma llamada en JavaScript (fetch o Axios), Python, Go, Java o C# y compárala con tu código. La diferencia suele ser una cabecera, la codificación del cuerpo o la URL.

Pruébalo en tu propio editor

Gratis, sin cuenta y en local. Para VS Code 1.93+ e IDE de JetBrains en Windows, macOS o Linux.

code --install-extension sayaib.hue-console