Los códigos de estado HTTP son los números de tres dígitos que el servidor devuelve al inicio de cada respuesta para resumir qué ocurrió. Son la forma en que navegadores, clientes, proxies y CDN deciden si cachear, redirigir, reintentar o mostrar un error al usuario.
Cada código pertenece a una de cinco clases según su primer dígito: 1xx informativos, 2xx éxito, 3xx redirección, 4xx error del cliente, 5xx error del servidor. Cuando conoces la clase, ya tienes una idea bastante buena del significado aunque no recuerdes el código exacto.
La mayoría de aplicaciones solo usa un núcleo pequeño (200, 201, 204, 301, 302, 304, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503). Saber qué *significa* cada uno -y la diferencia entre 401 Unauthorized y 403 Forbidden, o entre 301 Moved Permanently y 302 Found- es lo que marca la diferencia como desarrollador backend o de APIs.
Lo que vas a aprender usando esta referencia
El primer dígito siempre indica la clase: 1xx info, 2xx éxito, 3xx redirección, 4xx error del cliente, 5xx error del servidor.
Los códigos de estado son *parte del contrato* que ofrece una API: los clientes deben ramificar según el código, no parsear mensajes de error del cuerpo.
4xx significa que el cliente hizo algo mal (datos incorrectos, falta de autenticación, recurso inexistente). 5xx significa que el servidor falló, independientemente de lo que hiciera el cliente.
Cómo usar la referencia de códigos de estado paso a paso
1
Busca por código o por nombre
Escribe un número (404, 429) o una palabra clave (auth, redirect, rate limit) y los códigos coincidentes se filtran al instante.
2
Filtra por clase
Usa los chips de clase (1xx, 2xx, 3xx, 4xx, 5xx) para acotar la lista cuando estás explorando en lugar de buscar algo concreto.
3
Lee la explicación en lenguaje claro
Cada entrada incluye cuándo se envía el código, el comportamiento típico del cliente y la causa más habitual.
4
Compara códigos relacionados
Aprovecha los enlaces "ver también" entre parejas confusas (401 vs 403, 301 vs 302) para elegir el correcto en tu API.
Clases de códigos de estado HTTP
Las cinco clases de códigos de estado HTTP y lo que significan de un vistazo. Definidas en el RFC 9110 y registradas en el IANA HTTP Status Code Registry.
Éxito, pero sin cuerpo. Habitual tras llamadas DELETE o PUT que no necesitan devolver datos.
Los tres son códigos de éxito; la diferencia está en lo que lleva la respuesta. 201 debería incluir una cabecera Location que apunte al recurso recién creado; 204, por definición, va sin cuerpo.
Redirección temporal. Los navegadores vuelven a consultar la URL original en cada petición; los marcadores se mantienen en la URL antigua.
Usa 301 cuando realmente has movido un recurso (rebranding, cambio de estructura de URLs). Usa 302 para redirecciones cortas, como tests A/B, redirecciones de login o páginas de mantenimiento.
El servidor sabe quién eres, pero no tienes permiso sobre este recurso.
Si enviar credenciales distintas podría arreglarlo, devuelve 401. Si ninguna credencial serviría (el recurso simplemente está vetado para este usuario), devuelve 403.
Gateway timeout: un proxy llegó hasta el upstream, pero no recibió respuesta a tiempo.
Los cuatro son errores de servidor, pero cuentan historias muy distintas a quien depura. 500 apunta a tu aplicación; 502 y 504, al camino de red; 503, a la capacidad.
Errores habituales con los códigos de estado HTTP
Devolver 200 OK con {"error": "..."} en el cuerpo. Los códigos de estado son parte del contrato: usa el correcto (400, 404, 500) para que los clientes puedan ramificar.
Usar 401 para errores de permisos. 401 es para autenticación; los permisos denegados son 403.
Usar 200 para recursos recién creados en lugar de 201 con cabecera Location.
Preguntas frecuentes sobre códigos HTTP
¿Qué significa HTTP 404?
404 Not Found significa que el servidor entendió la petición, pero el recurso de esa URL no existe. Lo más común es que la ruta esté mal, que el recurso se haya borrado o que la URL esté mal escrita.
¿Cuál es la diferencia entre 401 y 403?
401 Unauthorized significa que no estás autenticado: el servidor no sabe quién eres. 403 Forbidden significa que estás autenticado, pero no tienes permiso sobre el recurso. Cambiar de credenciales puede solucionar un 401; nunca arreglará un 403.
¿Cuál es la diferencia entre 301 y 302?
301 Moved Permanently es una redirección permanente: navegadores y buscadores actualizan sus registros. 302 Found es una redirección temporal: los clientes siguen visitando la URL original. Usa 301 para movimientos definitivos y 302 para desvíos puntuales.
¿Qué significa HTTP 500?
500 Internal Server Error es un error genérico del lado del servidor, normalmente lanzado cuando se propaga una excepción no controlada. El cliente no hizo nada mal: tu servidor falló al procesar una petición válida.
¿Conviene usar siempre un código de estado específico?
Sí. Devolver 200 OK para fallos o 500 para todo lo que va mal complica el uso de la API. Elige el código más específico que encaje: clientes, proxies, monitorización y lógica de reintentos se basan en el código de estado.
¿Qué significa HTTP 429?
429 Too Many Requests se envía cuando un cliente alcanzó un límite de tasa. La respuesta debería incluir una cabecera Retry-After que indique al cliente cuándo es seguro volver a intentarlo.
