¿Qué diferencia hay entre 401 y 403?

401 significa que el cliente no está autenticado, por ejemplo porque falta el token o ha caducado. 403 significa que el cliente está autenticado, pero no tiene permiso para hacer esto.

¿Los errores de validación deben devolver 400 o 422?

Se usan las dos. Una convención habitual es 400 para solicitudes que no se pueden analizar y 422 para solicitudes bien formadas cuyos valores no superan la validación.

¿Cuándo debo usar 301 y cuándo 308?

Ambas son redirecciones permanentes. Con 301, los navegadores pueden convertir un POST en un GET; 308 garantiza que se conservan el método y el cuerpo. Para simples cambios de ubicación de páginas, 301 está bien.

¿Qué diferencia hay entre 502 y 504?

Ambos vienen de un proxy o de un balanceador de carga. 502 significa que el servidor que tiene detrás devolvió una respuesta no válida o se bloqueó; 504 significa que no respondió a tiempo.

¿Qué significa el código de estado 0?

No es un estado HTTP. Los navegadores indican 0 cuando no ha llegado ninguna respuesta al script: la solicitud se bloqueó por CORS, se canceló, tuvo un error de red o de DNS, o se bloqueó por contenido mixto. Revisa la consola del navegador y la pestaña Red para ver el motivo real.

¿Está bien devolver 404 en lugar de 403?

Sí. El RFC 9110 permite que un servidor responda 404 cuando no quiere revelar que un recurso existe a alguien que quizá no deba verlo. GitHub lo hace con los repositorios privados. Usa 403 cuando el cliente puede saber que el recurso existe, pero no tiene permiso para acceder a él.

¿Qué códigos de estado se pueden almacenar en caché por defecto?

Según el RFC 9110, las respuestas con 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414 y 501 se pueden almacenar en caché de forma heurística cuando ninguna cabecera Cache-Control o Expires indica lo contrario. Así que una CDN puede seguir sirviendo un 404 durante un tiempo. Envía cabeceras de caché explícitas para controlarlo.

Códigos de estado HTTP

Todos los códigos de estado HTTP, con su significado y cuándo usarlos.

Acerca de esta herramienta

Busca cualquier código de estado HTTP por número o nombre. Cada uno tiene una descripción sencilla y una nota sobre cuándo devolverlo, lo que ayuda al diseñar una API o al revisar una solicitud que falla.

Cómo se usa

Escribe un código de estado, como 404, o una palabra, como redirección o límite.
Filtra por clase: 1xx informativos, 2xx éxito, 3xx redirecciones, 4xx errores del cliente, 5xx errores del servidor.
Consulta qué significa cada código y cuándo devolverlo.

Preguntas

¿Qué diferencia hay entre 401 y 403?: 401 significa que el cliente no está autenticado, por ejemplo porque falta el token o ha caducado. 403 significa que el cliente está autenticado, pero no tiene permiso para hacer esto.
¿Los errores de validación deben devolver 400 o 422?: Se usan las dos. Una convención habitual es 400 para solicitudes que no se pueden analizar y 422 para solicitudes bien formadas cuyos valores no superan la validación.
¿Cuándo debo usar 301 y cuándo 308?: Ambas son redirecciones permanentes. Con 301, los navegadores pueden convertir un POST en un GET; 308 garantiza que se conservan el método y el cuerpo. Para simples cambios de ubicación de páginas, 301 está bien.
¿Qué diferencia hay entre 502 y 504?: Ambos vienen de un proxy o de un balanceador de carga. 502 significa que el servidor que tiene detrás devolvió una respuesta no válida o se bloqueó; 504 significa que no respondió a tiempo.
¿Qué significa el código de estado 0?: No es un estado HTTP. Los navegadores indican 0 cuando no ha llegado ninguna respuesta al script: la solicitud se bloqueó por CORS, se canceló, tuvo un error de red o de DNS, o se bloqueó por contenido mixto. Revisa la consola del navegador y la pestaña Red para ver el motivo real.
¿Está bien devolver 404 en lugar de 403?: Sí. El RFC 9110 permite que un servidor responda 404 cuando no quiere revelar que un recurso existe a alguien que quizá no deba verlo. GitHub lo hace con los repositorios privados. Usa 403 cuando el cliente puede saber que el recurso existe, pero no tiene permiso para acceder a él.
¿Qué códigos de estado se pueden almacenar en caché por defecto?: Según el RFC 9110, las respuestas con 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414 y 501 se pueden almacenar en caché de forma heurística cuando ninguna cabecera Cache-Control o Expires indica lo contrario. Así que una CDN puede seguir sirviendo un 404 durante un tiempo. Envía cabeceras de caché explícitas para controlarlo.

¿Qué son los códigos de estado HTTP?

Toda respuesta HTTP empieza con un código de estado de tres dígitos que indica al cliente cómo ha ido la solicitud. Los códigos y sus significados se definen en el RFC 9110, con algunos añadidos por otros RFC, como 429 Too Many Requests, del RFC 6585. El primer dígito indica la clase: 1xx informativo, 2xx éxito, 3xx redirección, 4xx error del cliente y 5xx error del servidor. Un cliente que no conoce un código lo trata como el código x00 de su clase.

La clase es lo que tiene en cuenta la mayoría del software. Los navegadores siguen las redirecciones 3xx, la lógica de reintentos suele reintentar algunas respuestas 5xx pero casi nunca las 4xx, y la monitorización cuenta los 5xx como errores de tu lado. La frase de motivo que sigue al número, como “Not Found”, es solo informativa, y HTTP/2 la elimina por completo. Por eso elegir el número correcto importa más que el mensaje que envíes con él.

¿Qué código de estado HTTP debe devolver mi API?

Empieza por los casos habituales. Devuelve 200 para una lectura o actualización correcta con cuerpo, 201 con una cabecera Location cuando un POST crea algo y 204 cuando no hay nada que devolver, como tras un DELETE. Usa 202 cuando el trabajo queda en cola y termina más tarde. Evita devolver 200 con un mensaje de error en el cuerpo: los clientes, las cachés y las herramientas de monitorización confían primero en el código de estado.

Para los errores, separa la culpa del cliente de la tuya. Usa 400 para una entrada mal formada, 404 cuando el recurso no existe, 409 para conflictos como una dirección de correo duplicada y 429 con una cabecera Retry-After para los límites de frecuencia. Reserva los 5xx para los fallos del lado del servidor, y registra los detalles en lugar de devolver trazas de pila. Un cuerpo de error coherente, como Problem Details del RFC 9457, ayuda a los clientes a mostrar mensajes útiles.

Cómo comprobar el código de estado de una solicitud

En el navegador, abre las herramientas para desarrolladores, ve a la pestaña Red (Network) y recarga la página. La columna Estado (Status) muestra el código de cada solicitud, incluidas las llamadas fetch fallidas que hacen los scripts. En la línea de comandos, curl -i muestra la línea de estado y las cabeceras de la respuesta antes del cuerpo, curl -I envía una solicitud HEAD para mostrar solo las cabeceras, y si añades -L sigue las redirecciones para que veas cada salto.

Cuando un código te sorprenda, averigua quién lo envió. Un 502, 503 o 504 suele venir de nginx, un balanceador de carga o una CDN y no de tu aplicación, así que revisa la cabecera Server y los logs del proxy. Un 404 en una ruta que sabes que existe suele indicar una ruta base incorrecta o una discrepancia con la barra final, mientras que 405 significa que la ruta existe, pero no para ese método. El conversor de curl ayuda a reconstruir la solicitud que falla.

Todos los códigos de estado HTTP

Todos los códigos de estado con su significado y cuándo devolverlos, agrupados por clase.

Informativo (1xx)

Código	Nombre	Significado	Cuándo usarlo
100	Continue	El servidor recibió las cabeceras de la solicitud; el cliente debe enviar el cuerpo.	Se envía automáticamente cuando un cliente pregunta con Expect: 100-continue.
101	Switching Protocols	El servidor cambia al protocolo que pidió el cliente.	Al actualizar una conexión a WebSocket.
103	Early Hints	Cabeceras preliminares para que el navegador pueda empezar a precargar.	Envía cabeceras Link para CSS y fuentes mientras la página aún se está generando.

Éxito (2xx)

Código	Nombre	Significado	Cuándo usarlo
200	OK	La solicitud se completó correctamente.	Lo habitual para un GET correcto o un POST que devuelve un resultado.
201	Created	Se creó un recurso nuevo.	Tras un POST que crea algo. Incluye una cabecera Location que apunte a ello.
202	Accepted	La solicitud se aceptó, pero aún no se ha procesado.	Tareas en cola o en segundo plano. Devuelve una forma de consultar el progreso.
204	No Content	Correcto, sin nada que devolver.	Un DELETE o PUT que no devuelve cuerpo.
206	Partial Content	Solo se devuelve una parte del recurso.	Al responder a una solicitud Range, para streaming de vídeo o descargas reanudables.

Redirección (3xx)

Código	Nombre	Significado	Cuándo usarlo
301	Moved Permanently	El recurso tiene una nueva URL permanente.	URL antiguas tras reestructurar un sitio. Los navegadores y los buscadores lo recuerdan.
302	Found	El recurso está temporalmente en otra URL.	Redirecciones de corta duración. Los clientes pueden cambiar POST por GET; mejor usa 303 o 307 para ser explícito.
303	See Other	Obtén el resultado desde otra URL con GET.	Redirigir tras el POST de un formulario para que recargar la página no lo vuelva a enviar.
304	Not Modified	La copia en caché sigue siendo válida.	Al responder a una solicitud condicional con If-None-Match o If-Modified-Since.
307	Temporary Redirect	Repite la misma solicitud en otra URL.	Redirección temporal que debe conservar el método y el cuerpo.
308	Permanent Redirect	Repite la misma solicitud en una nueva URL permanente.	Como 301, pero el método y el cuerpo no deben cambiar.

Error del cliente (4xx)

Código	Nombre	Significado	Cuándo usarlo
400	Bad Request	La solicitud está mal formada o no es válida.	JSON que no se puede analizar, campos obligatorios ausentes, tipos incorrectos.
401	Unauthorized	Falta la autenticación o no es válida.	Sin token o con uno caducado. Pese al nombre, significa “no autenticado”.
402	Payment Required	Reservado; algunas API lo usan para problemas de facturación.	Límite del plan alcanzado o pago fallido.
403	Forbidden	El cliente es conocido, pero no tiene permiso para hacer esto.	Sesión iniciada, pero sin permiso.
404	Not Found	No existe nada en esta URL.	Rutas o ID desconocidos. También se usa para ocultar recursos que el cliente no debería conocer.
405	Method Not Allowed	Esta URL no admite ese método HTTP.	Un POST a un endpoint de solo lectura. Incluye una cabecera Allow.
406	Not Acceptable	Ninguna representación coincide con la cabecera Accept.	El cliente pidió XML a una API que solo usa JSON.
408	Request Timeout	El cliente tardó demasiado en enviar la solicitud.	Conexiones inactivas. Los clientes pueden reintentar sin riesgo.
409	Conflict	La solicitud entra en conflicto con el estado actual.	Valores únicos duplicados o una edición basada en una versión obsoleta.
410	Gone	El recurso existió, pero se eliminó para siempre.	Contenido eliminado o versiones de API retiradas. Más contundente que 404.
411	Length Required	Se requiere una cabecera Content-Length.	Subidas sin tamaño declarado.
412	Precondition Failed	Una cabecera condicional no coincidió.	If-Match con un ETag desactualizado, para evitar perder actualizaciones.
413	Content Too Large	El cuerpo de la solicitud es mayor de lo que acepta el servidor.	Subidas que superan el límite de tamaño.
414	URI Too Long	La URL es más larga de lo que admite el servidor.	Cadenas de consulta enormes. Pasa los datos al cuerpo de un POST.
415	Unsupported Media Type	El formato del cuerpo no es compatible.	Al enviar datos de formulario a un endpoint JSON, o con un Content-Type incorrecto.
416	Range Not Satisfiable	El rango de bytes solicitado está fuera del archivo.	Una solicitud Range más allá del final del recurso.
418	I’m a teapot	Una broma del 1 de abril de 1998 que se quedó para siempre.	Solo para huevos de pascua.
422	Unprocessable Content	La solicitud está bien formada, pero no supera la validación.	JSON válido con valores no válidos, como una fecha de fin anterior a la de inicio.
423	Locked	El recurso está bloqueado.	WebDAV, o un registro que otra persona está editando.
425	Too Early	El servidor no se arriesga a procesar una solicitud que podría repetirse.	Datos anticipados de TLS (0-RTT).
426	Upgrade Required	El cliente debe cambiar a otro protocolo.	Para forzar una versión más reciente de TLS o HTTP.
428	Precondition Required	La solicitud debe ser condicional.	Al exigir If-Match en las actualizaciones para evitar escrituras perdidas.
429	Too Many Requests	El cliente envía solicitudes demasiado rápido.	Limitación de frecuencia. Incluye una cabecera Retry-After.
431	Request Header Fields Too Large	Las cabeceras son demasiado grandes.	Las cookies demasiado grandes suelen ser las culpables.
451	Unavailable For Legal Reasons	Bloqueado por motivos legales.	Contenido retirado por orden judicial o bloqueado en un país.

Error del servidor (5xx)

Código	Nombre	Significado	Cuándo usarlo
500	Internal Server Error	Algo salió mal en el servidor.	Excepciones no controladas. Registra los detalles, no se los muestres al cliente.
501	Not Implemented	El servidor no admite esta funcionalidad.	Un método HTTP que el servidor no reconoce en absoluto.
502	Bad Gateway	Un proxy recibió una respuesta no válida del servidor que tiene detrás.	La aplicación detrás de nginx o de un balanceador de carga se bloqueó o devolvió basura.
503	Service Unavailable	El servidor no puede atender solicitudes ahora mismo.	Mantenimiento o sobrecarga. Incluye Retry-After si sabes cuándo volverá a funcionar.
504	Gateway Timeout	Un proxy no recibió respuesta a tiempo.	La aplicación de origen es demasiado lenta o está colgada.
505	HTTP Version Not Supported	La versión de HTTP no es compatible.	Poco habitual; versiones de protocolo muy antiguas o muy nuevas.
507	Insufficient Storage	El servidor no tiene espacio para guardar el resultado.	Disco lleno o cuota de almacenamiento alcanzada.
508	Loop Detected	El servidor encontró un bucle infinito durante el procesamiento.	WebDAV, o un ciclo de redirecciones o de proxy.
511	Network Authentication Required	El cliente debe iniciar sesión para obtener acceso a la red.	Portales cautivos en el wifi de hoteles y aeropuertos.

¿Algo no funciona o un resultado parece incorrecto? Informar de un problema con esta herramienta