Códigos de estado HTTP: La guía completa para desarrolladores (2026)

Los códigos de estado HTTP no son solo memorización

Cada respuesta HTTP lleva un código de estado de tres dígitos. La mayoría de los desarrolladores los tiene memorizados hasta cierto punto — 200 significa bien, 404 significa no encontrado, 500 significa que algo se rompió. Pero la imagen completa es más interesante y más útil que eso.

Entender bien los códigos de estado HTTP significa escribir mejores APIs, depurar más rápido y tomar decisiones más inteligentes sobre redirecciones, caché y manejo de errores. Esta guía es una referencia práctica, no un volcado de RFC.

Para consultar rápidamente un código mientras trabajas, la herramienta HTTP Status Codes te da descripciones instantáneas y notas de uso.

---

Las cinco categorías: un modelo mental

Los códigos de estado HTTP se agrupan en cinco clases. El primer dígito te indica la categoría:

Rango	Categoría	El resumen
1xx	Informacional	"Espera, aún estoy trabajando..."
2xx	Éxito	"Aquí tienes."
3xx	Redirección	"Está por allá."
4xx	Error del cliente	"Tú cometiste un error."
5xx	Error del servidor	"Nosotros cometimos un error."

Esta taxonomía vale la pena interiorizarla. Cuando ves un código de estado desconocido, el primer dígito solo ya te dice si debes buscar el problema en tu solicitud o en el servidor.

---

2xx: Códigos de éxito

Estos son los que quieres ver. Pero no todos son iguales.

200 OK

El éxito predeterminado. La solicitud funcionó, aquí está el cuerpo de la respuesta. Para solicitudes GET y generalmente para POST/PUT cuando devuelves el recurso actualizado.

201 Created

Se usa cuando un recurso se crea exitosamente — típicamente en respuesta a un POST. La buena práctica es incluir un encabezado Location apuntando al nuevo recurso.

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "María García", "email": "maria@ejemplo.es"}'
# HTTP/2 201
# Location: /users/43

Muchas APIs devuelven 200 para todo. Funciona, pero es descuidado. Devolver 201 con un encabezado Location da a los desarrolladores clientes un contrato mucho más claro.

204 No Content

La solicitud fue exitosa pero no hay nada que devolver. Perfecto para operaciones DELETE, o PUT/PATCH cuando no necesitas enviar de vuelta el recurso actualizado.

Nunca devuelvas un cuerpo con 204. Si necesitas retornar datos después de una eliminación, usa 200.

---

3xx: Redirecciones

Aquí es donde los desarrolladores cometen los errores más costosos — las implicaciones de SEO y caché son fáciles de ignorar.

301 Moved Permanently

El recurso se ha movido permanentemente a una nueva URL. Los navegadores cachean esta redirección indefinidamente. Los motores de búsqueda transfieren el valor de los enlaces (PageRank) a la nueva URL.

Cuidado: Una vez en caché, un 301 es muy difícil de deshacer. Los navegadores pueden cachearlo durante meses. Si no estás 100% seguro de que la redirección es permanente, usa 302.

302 Found

Redirección temporal. El navegador la sigue pero no la cachea permanentemente. El valor SEO permanece en la URL original. Para pruebas A/B, páginas de mantenimiento y redirecciones post-login.

307 / 308

307 es la versión que preserva el método de 302 (temporal), 308 la versión que preserva el método de 301 (permanente). Al redirigir un POST, esto asegura que el método no cambie a GET.

304 Not Modified

El cliente envió un GET condicional y la versión cacheada aún es válida. El servidor envía solo el código, sin cuerpo. Así funciona el caché HTTP eficientemente.

---

4xx: Errores del cliente

El cliente envió algo incorrecto. Aquí es donde ocurre la mayoría de la depuración de APIs.

400 Bad Request

Un código comodín para solicitudes malformadas — campos obligatorios faltantes, JSON inválido, errores de tipo. Sé lo más específico posible en el cuerpo de la respuesta.

{
  "error": "validation_failed",
  "details": [
    { "field": "email", "message": "Debe ser una dirección de email válida" },
    { "field": "age", "message": "Debe ser un número entero positivo" }
  ]
}

401 Unauthorized

La solicitud requiere autenticación y el cliente no la proporcionó o proporcionó credenciales inválidas. A pesar del nombre "Unauthorized", este código es sobre autenticación, no autorización.

403 Forbidden

El cliente está autenticado pero no tiene permiso para acceder al recurso. El servidor sabe quién eres — simplemente no te deja entrar.

Esta distinción importa:

• Intentar acceder a datos privados de otra persona → 403
• Acceder a la API sin token → 401
• Acceder a un endpoint que no está incluido en tu suscripción → 403

404 Not Found

El recurso no existe. Un matiz: algunas APIs devuelven 404 cuando el usuario no tiene permiso de ver un recurso, para evitar revelar su existencia. Es legítimo para recursos sensibles a la seguridad.

409 Conflict

La solicitud entra en conflicto con el estado actual del recurso. Casos clásicos: crear un usuario con un email que ya existe, o fallo de bloqueo optimista.

422 Unprocessable Entity

La solicitud es sintácticamente válida (JSON parseable, Content-Type correcto) pero semánticamente inválida — viola reglas de negocio. Muchas APIs modernas prefieren 422 sobre 400 para errores de validación.

• 400: "Ni siquiera puedo parsear lo que me enviaste"
• 422: "Lo parseé bien, pero no tiene sentido"

429 Too Many Requests

Alcanzaste un límite de velocidad. La respuesta debe incluir Retry-After y los encabezados X-RateLimit-*.

418 I'm a Teapot

Definido en el RFC 2324 como una broma de Día de los Inocentes — el protocolo de control de cafetera de hipertexto (HTCPCP). El servidor se niega a preparar café porque es una tetera. Google devuelve este código para ciertas solicitudes. El estándar más inútil y más querido de Internet.

---

5xx: Errores del servidor

Algo salió mal en el servidor. El cliente no hizo nada malo.

500 Internal Server Error

El código genérico "algo se rompió". Generalmente significa una excepción no manejada. Registra todo, nunca expongas stack traces en las respuestas, y configura alertas en producción.

502 Bad Gateway

El servidor actuaba como gateway o proxy y recibió una respuesta inválida del servidor upstream. Común en configuraciones nginx + Node.js cuando el proceso Node falla o expira.

503 Service Unavailable

El servidor no puede manejar temporalmente la solicitud — sobrecargado o en mantenimiento. Incluye un encabezado Retry-After.

504 Gateway Timeout

El gateway no recibió una respuesta oportuna del servidor upstream. Síntoma clásico de consultas SQL lentas, APIs externas que expiran o funciones Lambda alcanzando su límite de ejecución.

---

Códigos de estado HTTP en diseño de API REST

Hoja de referencia práctica:

GET /users → 200 (lista)

GET /users/ → 200 (encontrado), 404 (no encontrado), 403 (prohibido)

POST /users → 201 (creado), 400/422 (error de validación), 409 (conflicto)

PUT /users/ → 200 (actualizado con cuerpo), 204 (actualizado sin cuerpo), 404, 409

DELETE /users/ → 204 (eliminado), 404 (no encontrado)

La consistencia es clave

Las peores APIs son las APIs inconsistentes. Decide si usas 400 o 422 para errores de validación, si devuelves el recurso después de actualizaciones (200) o no (204), y mantén eso en todas partes.

No devolver 200 para todo

Algunas APIs devuelven {"success": false, "error": "not found"} con HTTP 200. Esto rompe las bibliotecas clientes, dificulta el monitoreo e ignora un estándar perfectamente bueno. Usa los códigos de estado correctos.

---

Guía rápida de depuración

¿Ves un 4xx? El problema está en la solicitud. Revisa encabezados, cuerpo, autenticación, Content-Type.

¿Ves un 5xx? El problema está en el servidor. Revisa logs, dependencias upstream, límites de recursos.

¿Ves 200 pero datos incorrectos? Ahora estás en territorio de lógica de aplicación — la capa de transporte está bien.

# Solo verificar código de estado y encabezados
curl -I https://api.example.com/endpoint

# Solicitud/respuesta completa con detalles
curl -v https://api.example.com/endpoint

# Con encabezado de autorización
curl -v -H "Authorization: Bearer your-token" https://api.example.com/users/me

---

Conclusión

Los códigos de estado HTTP son un protocolo de comunicación entre los desarrolladores de cliente y servidor. Usarlos correctamente es una forma de cortesía profesional — hace el trabajo más fácil para todos, desde el desarrollador frontend que consume tu API hasta el ingeniero de guardia depurando un incidente en producción a las 2 de la mañana.

Guarda la herramienta HTTP Status Codes en tus favoritos para consultas rápidas mientras desarrollas.