Cómo depurar errores de API REST: CORS, 401, 403, 404, 415 y timeouts
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.
Tu aplicación añade capas: una biblioteca HTTP, interceptores, un proxy, el navegador. Quítalas primero.
- En el navegador, abre DevTools → Network, haz clic con el botón derecho en la solicitud fallida y elige Copy → Copy as cURL.
- 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.
- 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.
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"}.
| Estado | Qué suele significar | Revisa primero |
|---|---|---|
400 Bad Request | El cuerpo o los parámetros no son válidos | El cuerpo de la respuesta; los campos obligatorios; la sintaxis JSON |
401 Unauthorized | No se enviaron credenciales válidas | La cabecera Authorization; la caducidad del token |
403 Forbidden | Las credenciales son válidas pero no tienen permiso para esto | Los scopes o roles del token; los permisos de la clave de API |
404 Not Found | URL incorrecta, o el recurso no existe | La URL base, la ruta, la barra final, la versión de la API |
405 Method Not Allowed | URL correcta, método incorrecto | GET frente a POST; la cabecera de respuesta Allow |
415 Unsupported Media Type | El servidor no puede leer el formato del cuerpo | La cabecera Content-Type |
422 Unprocessable Entity | JSON válido, pero no superó la validación | La lista de errores por campo del cuerpo de la respuesta |
429 Too Many Requests | Límite de peticiones alcanzado | La cabecera Retry-After |
5xx | El servidor falló | Los logs del servidor; si otra entrada funciona |
- ¿Está la cabecera? Algunos clientes HTTP descartan
Authorizational 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 palabraBeareruna sola vez. UnBearer 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énaud(audiencia) eiss(emisor) con lo que espera la API. El decodificador se ejecuta en local, así que un token real nunca va a un sitio web.
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.
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 (
/frente av1/ /).v2/ - La barra final:
/yusers /son rutas distintas en muchos servidores.users/ - Parámetros de ruta que nunca se sustituyeron, como
/ousers/ undefined /.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.
Un cuerpo JSON necesita Content-Type: application/. 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.
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/ (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 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:/y/ localhost:3000 http:/son orígenes distintos./ localhost:5173 - Falla la solicitud preflight
OPTIONS. Las solicitudes con cuerpo JSON o con cabeceraAuthorizationprovocan una preflight. Si el servidor responde con401,404o405(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 yAccess-Control-Allow-Credentials: true. No se permiteAccess-Control-Allow-Origin: *. - Errores sin cabeceras CORS. Si el servidor devuelve un
500sin 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.
- 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
localhostdesde 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.define el valor por defecto (30 segundos), un tiempo límite por solicitud lo sustituye y Cancel detiene una solicitud antes de tiempo.apiTimeout
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.