Códigos de estado HTTP explicados para developers — qué significa cada código

Por qué necesitas entender los códigos de estado HTTP#

Tu sitio de e-commerce devuelve un error 500 durante el checkout. Los clientes ven "Algo ha salido mal". ¿Pero qué ha salido mal en realidad? El servidor funciona. La base de datos está activa. El problema es algo completamente distinto, pero el 500 no te lo dice.

Tu endpoint de API devuelve un error 429 y tu app móvil crashea en lugar de mostrar un mensaje de reintento. Los usuarios piensan que la app está rota cuando en realidad tu rate limiter está haciendo su trabajo.

Tu página de estado dice "All Systems Operational" pero los clientes informan de páginas que cargan como 403 Forbidden. Tu monitoring no lo detectó porque solo comprueba la homepage.

Los códigos de estado HTTP son señales. Te dicen qué ha ido mal y dónde mirar. Pero solo si entiendes qué significa cada código.

Esta guía explica cada código de estado HTTP que te encontrarás, qué lo provoca y qué hacer cuando veas uno.

---

Códigos de estado HTTP: el panorama completo#

Las respuestas HTTP se organizan en cinco clases:

• 1xx (100-199): Informativo — "Solicitud recibida, procesando"
• 2xx (200-299): Éxito — "Todo ha funcionado"
• 3xx (300-399): Redirección — "Prueba en otro sitio"
• 4xx (400-499): Client Error — "La has liado tú"
• 5xx (500-599): Server Error — "La hemos liado nosotros"

Cada clase te dice dónde está el problema. Si recibes errores 4xx, el problema está en la solicitud (URL incorrecta, autenticación incorrecta, datos faltantes). Si recibes errores 5xx, el problema está en tu servidor.

---

Códigos de éxito 2xx (Todo ha ido bien)#

200 OK#

Qué significa: La solicitud se ha completado correctamente. El body de la respuesta contiene los datos solicitados.

Cuándo lo ves:

• El navegador carga una página web
• La API devuelve datos JSON
• El envío de un formulario tiene éxito

Ejemplo:

GET /api/users/123
Response: 200 OK
Body: {"id": 123, "name": "John", "email": "john@example.com"}

Acción: Ninguna. Todo está funcionando correctamente.

201 Created#

Qué significa: La solicitud se ha completado y se ha creado un nuevo recurso. La respuesta incluye el recurso recién creado.

Cuándo lo ves:

• POST para crear un nuevo usuario devuelve 201 Created
• Crear un nuevo pedido devuelve 201 Created
• Subir un archivo devuelve 201 Created

Ejemplo:

POST /api/users
Request: {"name": "Jane", "email": "jane@example.com"}
Response: 201 Created
Body: {"id": 456, "name": "Jane", "email": "jane@example.com", "created_at": "2026-02-20T10:00:00Z"}

Acción: Ninguna. El recurso se ha creado correctamente.

202 Accepted#

Qué significa: La solicitud se ha aceptado para procesarla, pero todavía no se ha procesado. Se usa para operaciones asíncronas.

Cuándo lo ves:

• Enviar un job de larga duración (p. ej. encoding de vídeo, generación de informes)
• Operaciones de procesamiento batch
• Tareas que se procesarán en segundo plano

Ejemplo:

POST /api/batch-emails/send
Request: {"recipient_ids": [1,2,3,...,10000]}
Response: 202 Accepted
Body: {"job_id": "job_12345", "status": "queued"}

Acción: La tarea está en cola. Vuelve a comprobar más tarde usando el ID del job para ver el estado.

204 No Content#

Qué significa: La solicitud se ha completado correctamente, pero no hay contenido que devolver.

Cuándo lo ves:

• Solicitudes DELETE (se ha eliminado correctamente, nada que devolver)
• PATCH exitoso sin body de respuesta
• Confirmaciones de webhooks

Ejemplo:

DELETE /api/users/123
Response: 204 No Content
Body: (vacío)

Acción: Ninguna. La acción se ha completado correctamente.

---

Códigos de redirección 3xx (Prueba en otro sitio)#

301 Moved Permanently#

Qué significa: El recurso se ha movido permanentemente a una nueva URL. Los motores de búsqueda actualizan su índice y los navegadores usan la nueva URL para futuras solicitudes.

Cuándo lo ves:

• Sitio web migrado de www.oldsite.com a newsite.com
• Endpoint antiguo de API reemplazado por uno nuevo
• La estructura de URLs ha cambiado

Ejemplo:

GET /old-page.html
Response: 301 Moved Permanently
Header: Location: /new-page.html

Acción:

• Para usuarios: el navegador sigue automáticamente la redirección (transparente)
• Para SEO: asegúrate de usar 301 para cambios permanentes (Google transfiere el page rank)
• Para APIs: los clientes deben actualizarse para usar la nueva URL

302 Found (Redirección temporal)#

Qué significa: El recurso se ha movido temporalmente a otra URL. La URL original sigue siendo válida, así que los navegadores NO cachean la nueva URL.

Cuándo lo ves:

• Redirecciones temporales durante mantenimiento
• Redirecciones a la página de login
• Tests A/B (redirigir a algunos usuarios a la nueva versión temporalmente)

Ejemplo:

GET /products/discount-flash-sale
Response: 302 Found
Header: Location: /products/2026-flash-sale

Acción: El navegador sigue temporalmente la redirección, pero sigue tratando la URL original como principal.

304 Not Modified#

Qué significa: El recurso no ha cambiado desde tu última solicitud. Usa la versión cacheada.

Cuándo lo ves:

• El navegador comprueba si la página web ha cambiado desde la última visita (comprueba la fecha de modificación/ETag)
• La API devuelve 304 si los datos no han cambiado desde la última solicitud
• Reduce el ancho de banda al evitar reenviar datos sin cambios

Ejemplo:

GET /api/user-profile
Request Header: If-Modified-Since: 2026-02-19 10:00:00
Response: 304 Not Modified
Body: (vacío — usa la versión cacheada de antes)

Acción: El navegador/cliente usa la versión cacheada localmente.

307 Temporary Redirect#

Qué significa: Como el 302, pero garantiza que el método HTTP se mantiene durante la redirección.

Diferencia técnica:

• 302 permite cambiar el método (POST → GET tras la redirección)
• 307 preserva el método (POST → POST tras la redirección)

Cuándo lo ves:

• Envío de formularios que redirigen a una página de confirmación (POST → POST)
• Redirecciones de API que deben preservar el método

Por qué importa: Los navegadores antiguos a veces convertían las redirecciones POST en GET, lo que podía perder los datos del formulario. El 307 evita esto.

---

Códigos de error 4xx del cliente (La has liado tú)#

400 Bad Request#

Qué significa: La solicitud está mal formada. El servidor no ha podido entenderla.

Cuándo lo ves:

• JSON mal formado en el body de la solicitud
• Faltan campos obligatorios
• Formato de parámetro inválido
• Error de sintaxis en la query string

Ejemplo:

POST /api/users
Request Body: {"name": "Jane" "email": "jane@example.com"}
                              ↑ Falta una coma
Response: 400 Bad Request
Body: {"error": "Invalid JSON syntax"}

Acción:

• Comprueba el formato de la solicitud
• Valida la sintaxis del JSON
• Asegúrate de que están presentes los campos obligatorios
• Verifica que los tipos de los parámetros coinciden con la documentación de la API

401 Unauthorized#

Qué significa: La autenticación ha fallado o falta. No has demostrado quién eres.

Cuándo lo ves:

• No se ha proporcionado un token de autenticación
• El token de autenticación no es válido o ha expirado
• Usuario/contraseña incorrectos
• Falta la API key

Ejemplo:

GET /api/user-profile
(Sin header Authorization)
Response: 401 Unauthorized
Body: {"error": "Authentication required"}

Acción:

• Proporciona una autenticación válida (login, API key, token, etc.)
• Refresca los tokens expirados
• Comprueba que las credenciales son correctas

403 Forbidden#

Qué significa: La autenticación se ha completado, pero no tienes permiso para acceder a este recurso.

Cuándo lo ves:

• Un usuario intenta eliminar la cuenta de otro usuario
• Un usuario intenta acceder a un endpoint solo para administradores
• Un usuario intenta acceder a un recurso de otra organización
• Permisos/roles insuficientes

Ejemplo:

DELETE /api/users/999
(Autenticado como usuario 123, intentando eliminar al usuario 999)
Response: 403 Forbidden
Body: {"error": "You can only delete your own account"}

Acción:

• Usa la cuenta correcta con los permisos apropiados
• Solicita permisos elevados si es necesario
• Verifica que estás accediendo al recurso correcto

404 Not Found#

Qué significa: El recurso no existe o el servidor no tiene ni idea de cómo gestionar este endpoint.

Cuándo lo ves:

• Errata en la URL (/users/ vs /users)
• El endpoint no existe
• Recurso eliminado
• Versión de API incorrecta

Ejemplo:

GET /api/users/nonexistent-id-12345
Response: 404 Not Found
Body: {"error": "User not found"}

Acción:

• Comprueba la ortografía de la URL
• Verifica que el endpoint existe
• Consulta la documentación de la API
• Prueba con un ID/recurso diferente

405 Method Not Allowed#

Qué significa: El endpoint existe, pero no soporta este método HTTP.

Cuándo lo ves:

• Usar POST en un endpoint que solo acepta GET
• Usar DELETE en un endpoint que no soporta eliminación
• Usar PATCH cuando solo se permite PUT

Ejemplo:

DELETE /api/domains/123
(Si DELETE no está soportado en el endpoint de domains)
Response: 405 Method Not Allowed
Header: Allow: GET, POST, PUT

Acción: Usa el método HTTP correcto. La respuesta normalmente incluye el header Allow mostrando los métodos válidos.

408 Request Timeout#

Qué significa: El servidor ha esperado demasiado a que el cliente enviara la solicitud y se ha rendido.

Cuándo lo ves:

• Cliente lento subiendo un archivo grande
• La conexión de red se cae a mitad de la solicitud
• La solicitud tarda más que el timeout del servidor (normalmente 30-300 segundos)

Ejemplo:

POST /api/upload
(Subir un archivo de 500MB en una conexión lenta tarda 10 minutos)
Response: 408 Request Timeout

Acción:

• Reintenta la solicitud
• Divide solicitudes grandes en partes más pequeñas
• Comprueba la conexión de red
• Aumenta el timeout del cliente si es apropiado

429 Too Many Requests#

Qué significa: Estás haciendo demasiadas solicitudes. Has superado el rate limit.

Cuándo lo ves:

• Has alcanzado el rate limit de la API (p. ej. 100 solicitudes/minuto)
• Envías emails demasiado rápido
• Haces intentos de login por fuerza bruta
• Un web scraper está atacando el servidor con demasiada intensidad

Ejemplo:

GET /api/users/123
(Solicitud número 100 del último minuto)
Response: 429 Too Many Requests
Header: Retry-After: 60
Body: {"error": "Rate limit exceeded. Try again in 60 seconds"}

Acción:

• Espera antes de reintentar (consulta el header Retry-After)
• Implementa exponential backoff
• Usa paginación para conjuntos de resultados grandes
• Cachea los resultados localmente en lugar de volver a solicitarlos

---

Códigos de error 5xx del servidor (La hemos liado nosotros)#

500 Internal Server Error#

Qué significa: Algo ha ido mal en el servidor y el servidor no puede dar más detalles.

Cuándo lo ves:

• Excepción no controlada en el código
• Conexión a la base de datos fallida
• Sin memoria
• Condición inesperada

Ejemplo:

POST /api/checkout
Response: 500 Internal Server Error
Body: {"error": "Something went wrong"}

Por qué es vago: Los servidores no exponen los detalles de los errores internos a los clientes por motivos de seguridad. Los errores detallados ayudan a los atacantes.

Acción:

• Revisa los logs del servidor para ver el error real
• Si es un servicio de terceros: contacta con soporte
• Si es tu servicio: revisa los logs de errores, reinicia si es necesario, haz rollback del último deployment

501 Not Implemented#

Qué significa: El servidor no soporta este método HTTP o esta funcionalidad.

Cuándo lo ves:

• El servidor no soporta funciones de HTTP/2
• WebSocket no soportado
• Ciertos métodos HTTP no implementados

Ejemplo:

OPTIONS /api/users
(El servidor no soporta el método OPTIONS)
Response: 501 Not Implemented

Acción: Normalmente nada — usa un método o servicio diferente. Raro en APIs modernas.

502 Bad Gateway#

Qué significa: El servidor ha recibido una respuesta inválida de un servidor upstream.

Escenarios reales:

1. Un proxy inverso (Nginx) no puede conectarse al backend

   Cliente → Nginx (gateway) → Backend Node.js
                   ↑
            El backend está caído o no responde
   

2. Un load balancer no puede llegar a ningún backend sano

   Cliente → Load Balancer → Servidores backend
                          ↑
              Todos los backends caídos o lentos
   

3. Un API Gateway no puede llegar a un microservicio

   Cliente → API Gateway → Auth Service (caído)
                        → User Service
                        → Order Service
   

Por qué pasa:

• El servidor backend ha crasheado
• Se ha perdido la conectividad de red
• El servidor upstream es lento y hace timeout
• El upstream devuelve una respuesta mal formada

Ejemplo:

GET /dashboard
Response: 502 Bad Gateway

Entre bastidores:

Nginx recibió la solicitud
Intentó reenviarla al servidor Node.js en localhost:3000
Connection refused (servidor no en ejecución)
Nginx devolvió: 502 Bad Gateway

Acción:

• Comprueba si los servicios backend están en ejecución: docker ps, pm2 status, estado de systemd
• Comprueba la conectividad de red al backend
• Revisa los logs del backend buscando crashes
• Reinicia el servicio backend si ha crasheado
• Comprueba si el load balancer está enrutando correctamente

503 Service Unavailable#

Qué significa: El servidor no puede gestionar las solicitudes temporalmente (mantenimiento, sobrecarga, dependencias caídas).

Cuándo lo ves:

• El servidor se está reiniciando
• El servidor está bajo carga pesada (todas las conexiones en uso)
• La base de datos está caída o se está migrando
• Una dependencia de terceros está caída
• Deployment en progreso (el tráfico está pausado)

Ejemplo:

GET /api/users
Response: 503 Service Unavailable
Header: Retry-After: 600
Body: {"error": "Server is undergoing maintenance. Try again in 10 minutes"}

Por qué los servidores devuelven 503 durante el mantenimiento:

• Le dice a los clientes "esto es temporal, prueba más tarde"
• Los navegadores y clientes saben que deben reintentar automáticamente
• Los motores de búsqueda no penalizan los 503 (a diferencia de los 500, que parecen un bug)

Acción:

• Espera y reintenta (consulta el header Retry-After para saber cuánto)
• Consulta la página de estado para ver las ventanas de mantenimiento
• Si es un servicio interno: espera a que termine el deployment, revisa los logs

504 Gateway Timeout#

Qué significa: El servidor no recibió una respuesta del servidor upstream a tiempo.

Cuándo lo ves:

• El servidor backend es demasiado lento
• La latencia de red es demasiado alta
• Una query de la base de datos está tardando demasiado
• El servidor upstream se ha colgado

Ejemplo:

Solicitud al backend:
GET /api/heavy-report
Esperar 30 segundos...
¡Timeout!
Response: 504 Gateway Timeout

Causa real:

Cliente → Nginx (timeout 30s) → Backend Node.js (query 60s)
                              ↑
              Nginx se rinde a los 30s
              El backend sigue ejecutando la query

Acción:

• Revisa el rendimiento del backend
• Busca queries lentas en la base de datos
• Optimiza el código
• Añade índices a la base de datos
• Aumenta el timeout si la operación legítimamente tarda más
• Divide las operaciones largas en jobs asíncronos

---

Tabla de referencia de códigos de estado HTTP#

Código	Nombre	Categoría	Significado
200	OK	Success	Solicitud exitosa
201	Created	Success	Recurso creado
202	Accepted	Success	Solicitud en cola para procesar
204	No Content	Success	Éxito, sin body de respuesta
301	Moved Permanently	Redirect	Usar la nueva URL permanentemente
302	Found	Redirect	Temporalmente en otra URL
304	Not Modified	Redirect	Usar versión cacheada
307	Temp Redirect	Redirect	Preserva el método HTTP en la redirección
400	Bad Request	Client Error	Solicitud mal formada
401	Unauthorized	Client Error	Autenticación requerida
403	Forbidden	Client Error	Acceso denegado
404	Not Found	Client Error	El recurso no existe
405	Method Not Allowed	Client Error	Método HTTP incorrecto
408	Request Timeout	Client Error	La solicitud ha tardado demasiado
429	Too Many Requests	Client Error	Rate limit excedido
500	Internal Server Error	Server Error	Error genérico del servidor
501	Not Implemented	Server Error	Funcionalidad no soportada
502	Bad Gateway	Server Error	Error en el servidor upstream
503	Service Unavailable	Server Error	Servidor temporalmente caído
504	Gateway Timeout	Server Error	Upstream demasiado lento

---

Cómo depurar problemas con códigos de estado HTTP#

Paso 1: Identificar el código de estado#

En el navegador:

1. Abre las Developer Tools (F12)
2. Ve a la pestaña Network
3. Mira la solicitud que ha fallado
4. La columna Status muestra el código

En la terminal:

curl -i https://example.com/endpoint
# La primera línea muestra: HTTP/1.1 200 OK

En la aplicación:

• Revisa los logs de errores
• Mira el objeto response
• La mayoría de frameworks exponen el código de estado

Paso 2: Entender qué significa#

Usa las categorías:

• ¿2xx? Funcionando como debe
• ¿3xx? Comprueba el destino de la redirección
• ¿4xx? Comprueba el formato y los permisos de la solicitud
• ¿5xx? Revisa los logs del servidor y las dependencias upstream

Paso 3: Mira el body y los headers de la respuesta#

Body de la respuesta: La mayoría de APIs incluyen los detalles del error:

{
  "error": "User not found",
  "message": "No user with ID 12345",
  "code": "USER_NOT_FOUND"
}

Headers de la respuesta: Los importantes:

• Retry-After — Cuánto esperar antes de reintentar (429, 503)
• Allow — Métodos HTTP válidos (405)
• Location — Dónde redirigir (3xx)
• WWW-Authenticate — Cómo autenticarse (401)

Paso 4: Actuar según la clase del código#

4xx Client Error:

• ¿Has enviado datos incorrectos? Arregla la solicitud
• ¿Hay una errata en la URL? Corrígela
• ¿No tienes permiso? Solicita acceso
• ¿El endpoint es incorrecto? Consulta la documentación

5xx Server Error:

• ¿Está el servidor en ejecución? Comprueba el uptime
• ¿Los logs muestran errores? Arregla el error
• ¿El upstream está caído? Espera a que se recupere
• ¿Se ha hecho un deployment? Haz rollback si es necesario

---

Ejemplo real: depurar un 502 Bad Gateway#

Escenario:

GET /api/checkout
Response: 502 Bad Gateway
Los clientes no pueden completar las compras

Paso 1: Confirmar que es un 502 ✓ El header de la respuesta muestra HTTP/1.1 502 Bad Gateway

Paso 2: Comprobar qué significa el 502 ✓ El servidor upstream no está respondiendo correctamente

Paso 3: Diagnosticar el problema

¿Están los servicios backend en ejecución?

docker ps
# Output: checkout-service is not running

✗ El servicio de checkout ha crasheado

Paso 4: Encontrar la causa raíz

Revisar los logs:

docker logs checkout-service
# Out of memory error!
# Java heap space exhausted

Paso 5: Arreglarlo

Aumentar la memoria:

docker-compose up -d --build

O reiniciar:

docker restart checkout-service

Paso 6: Verificar

curl -i https://api.example.com/api/checkout
# HTTP/1.1 200 OK ✓

---

Monitorizar códigos de estado en tiempo real#

Por qué deberías monitorizarlos#

• Detectar caídas antes de que los clientes las reporten
• Cazar errores 5xx que solo afectan a ciertos endpoints
• Trackear errores 4xx para detectar mal uso de la API
• Monitorizar rate limits 429 para saber cuándo escalar

Qué monitorizar#

Crítico (avisar si está caído):

• Cualquier error 5xx en endpoints críticos (checkout, login, pago)

Importante (investigar):

• Pico de errores 429 (el rate limiting significa que estás cerca de la capacidad)
• Aumento de errores 502/504 (degradación del upstream)
• Aumento de errores 403/401 (posible ataque por fuerza bruta)

Informativo (seguir tendencias):

• Errores 404 (¿se solicitan URLs incorrectas?)
• Errores 400 (¿los clientes envían solicitudes mal formadas?)

Usar Nova Uptime para monitorizar códigos de estado#

El uptime monitoring de Nova Uptime trackea los códigos de estado HTTP en tiempo real:

1. ¿Los monitores devuelven 200? El sitio está activo ✓
2. ¿Los monitores devuelven 404? URL incorrecta o endpoint eliminado ✗
3. ¿Los monitores devuelven 429? Te están aplicando rate limit ⚠️
4. ¿Los monitores devuelven 502/503? Problema en el backend ✗
5. ¿Los monitores devuelven 504? Timeout, hace falta optimización ⚠️

Nova Uptime te muestra:

• Qué códigos de estado se devuelven
• Cuándo empezaron a producirse
• Qué endpoints están afectados
• Tendencia a lo largo del tiempo

---

Códigos de estado HTTP y SEO#

Los motores de búsqueda usan los códigos de estado para decidir cómo indexar las páginas:

200 OK: Indexar esta página (normal)

301 Moved Permanently: Actualizar el índice para apuntar a la nueva URL

302 Found: Mantener la URL antigua en el índice, no seguir la redirección

304 Not Modified: No volver a rastrear, la última versión es la actual

401/403: No indexar (acceso denegado)

404 Not Found: Eliminar del índice (la página ha desaparecido)

410 Gone: Eliminar del índice (la página ha desaparecido y no volverá)

429/503/504: Reintentar más tarde (problema temporal)

Errores 5xx: Posible problema en el sitio; Google ralentiza el rastreo

Importante para la salud del sitio:

• Usa 301 para cambios permanentes de URL (preserva el valor SEO)
• Usa 410 para decirle explícitamente a Google que una página ha desaparecido
• Arregla los errores 5xx rápidamente (Google despriorixa los sitios rotos)
• Implementa robots.txt para prevenir 404 en contenido no indexable

---

Resumen: referencia rápida de códigos de estado HTTP#

Todo va bien:

• 200 OK — Éxito normal
• 201 Created — Nuevo recurso creado
• 204 No Content — Éxito, sin necesidad de respuesta

Redirección a otro sitio:

• 301/302 — Seguir la redirección a la nueva URL
• 304 — Usar la versión cacheada

Has cometido un error:

• 400 Bad Request — Arregla el formato de la solicitud
• 401 Unauthorized — Proporciona autenticación
• 403 Forbidden — No tienes permiso
• 404 Not Found — URL incorrecta
• 429 Too Many Requests — Más despacio, te están aplicando rate limit

Hemos cometido un error:

• 500 Internal Server Error — Revisa los logs del servidor
• 502 Bad Gateway — El servicio backend está caído
• 503 Service Unavailable — Servidor temporalmente caído
• 504 Gateway Timeout — El backend es demasiado lento

Monitorización con Nova Uptime: El monitoring HTTP de Nova Uptime detecta estos errores al instante y te avisa antes de que los clientes lo noten. Monitoriza endpoints críticos, sigue las tendencias de los códigos de estado y recibe alertas cuando los errores 5xx aumenten.

---

Última actualización: 20 de febrero de 2026 Nova Uptime monitoriza códigos de estado HTTP en más de 50 tipos de check y avisa de errores 5xx en tiempo real