Los códigos de estado HTTP son números de tres dígitos retornados por servidores en respuesta a solicitudes de clientes. Indican si una solicitud fue exitosa, falló debido a un error del cliente, falló debido a un error del servidor, o requiere una acción adicional como una redirección. Cada respuesta HTTP incluye exactamente un código de estado, convirtiéndolos en la primera información que un cliente o intermediario usa para determinar qué hacer a continuación.
Cómo Funcionan los Códigos de Estado HTTP
Las Cinco Clases de Códigos de Estado
Los códigos de estado se agrupan en cinco clases por su primer dígito:
| Clase | Rango | Significado | Ejemplo |
|---|---|---|---|
| 1xx | 100-199 | Informativo | 100 Continue |
| 2xx | 200-299 | Éxito | 200 OK, 201 Created |
| 3xx | 300-399 | Redirección | 301 Moved Permanently, 304 Not Modified |
| 4xx | 400-499 | Error del Cliente | 400 Bad Request, 404 Not Found |
| 5xx | 500-599 | Error del Servidor | 500 Internal Server Error, 502 Bad Gateway |
La frase de motivo después del código (“OK”, “Not Found”) es solo informativa. Los clientes deben usar el código numérico para la toma de decisiones (RFC 9110).
Códigos de Estado y Caché
No todos los códigos de estado deben almacenarse en caché. La RFC 9111 define la cacheabilidad por defecto:
| Código de Estado | Cacheable por Defecto |
|---|---|
| 200, 203, 204, 206, 300, 301, 404, 410 | Sí (a menos que Cache-Control prohíba) |
| 302, 307, 308 | Varía por implementación |
| 304 | Sí (valida contenido cacheado) |
| Otros 4xx (400, 401, 403, etc.) | No |
| 5xx | No |
Códigos de Estado y Comportamiento de Reintento
Clientes y proxies usan códigos de estado para decidir si reintentar:
| Código | Reintento Seguro? | Comportamiento de Reintento |
|---|---|---|
| 408 Request Timeout | Sí | Reintentar inmediatamente |
| 429 Too Many Requests | Sí | Reintentar después del retraso de Retry-After |
| 502 Bad Gateway | Métodos idempotentes solo | Reintentar con backoff |
| 503 Service Unavailable | Sí | Reintentar después del retraso de Retry-After |
| 504 Gateway Timeout | Métodos idempotentes solo | Reintentar con backoff |
| 400, 401, 403, 404, 405 | No | No reintentar (error del cliente) |
Códigos de Éxito 2xx Comunes
200 OK
La solicitud fue exitosa. El significado depende del método:
GET: Recurso retornado en el cuerpo de la respuestaPOST: Recurso creado o acción completadaPUT: Recurso actualizadoDELETE: Recurso eliminado
201 Created
Un nuevo recurso fue creado. Usado principalmente con solicitudes POST. La respuesta debe incluir un header Location apuntando al nuevo recurso.
204 No Content
La solicitud fue exitosa pero no hay contenido para retornar. Común para solicitudes DELETE o actualizaciones PUT donde el cliente ya tiene los datos.
206 Partial Content
El servidor está entregando parte de un recurso. Usado con solicitudes de rango para archivos grandes o streaming de video.
Códigos de Redirección 3xx Comunes
301 Moved Permanently
El recurso ha sido movido permanentemente a una nueva URL. Clientes y motores de búsqueda deben actualizar sus registros. El header Location contiene la nueva URL.
302 Found (Redirección Temporal)
El recurso está temporalmente en una URL diferente. Solicitudes futuras deben continuar usando la URL original.
304 Not Modified
El recurso no ha cambiado desde la última solicitud del cliente. Usado con headers condicionales como If-None-Match o If-Modified-Since. Ahorra ancho de banda al no reenviar contenido sin cambios.
307 Temporary Redirect / 308 Permanent Redirect
Como 302 y 301, pero preservan el método HTTP. Usa 307/308 en lugar de 302/301 para solicitudes POST o PUT para evitar convertir el método a GET.
Códigos de Error del Cliente 4xx Comunes
400 Bad Request
El servidor no puede procesar la solicitud debido a un error del cliente. Causas comunes:
- JSON o XML malformado en el cuerpo de la solicitud
- Parámetros requeridos ausentes
- Valores de parámetros inválidos
- Errores de sintaxis en la solicitud
401 Unauthorized
Se requiere autenticación. El cliente debe autenticarse antes de acceder al recurso. La respuesta debe incluir un header WWW-Authenticate indicando cómo autenticarse.
403 Forbidden
El cliente está autenticado pero no tiene permiso para acceder al recurso. A diferencia de 401, re-autenticarse no ayuda—el cliente simplemente no tiene permiso.
404 Not Found
El recurso solicitado no existe. Puede también retornarse en lugar de 403 por seguridad (para evitar confirmar que el recurso existe).
405 Method Not Allowed
El método de solicitud no está soportado para este recurso. La respuesta debe incluir un header Allow listando los métodos válidos.
408 Request Timeout
El servidor cerró una conexión inactiva. El cliente debe reintentar en una nueva conexión.
429 Too Many Requests
El cliente ha excedido los límites de tasa. Verifique el header Retry-After para cuándo reintentar.
413 Content Too Large
El cuerpo de la solicitud excede el límite configurado del servidor. El cliente debe reducir el tamaño del payload o usar upload fragmentado.
Códigos de Error del Servidor 5xx Comunes
500 Internal Server Error
Un error inesperado ocurrió en el servidor. Este es un código genérico para excepciones no manejadas y errores de configuración. El cliente no puede corregir este problema.
502 Bad Gateway
Un proxy o gateway recibió una respuesta inválida de un servidor upstream. Común en arquitecturas distribuidas con load balancers, CDNs o API gateways.
503 Service Unavailable
El servidor está temporalmente incapaz de manejar solicitudes. Causas comunes:
- Servidor sobrecargado
- Mantenimiento en progreso
- Agotamiento de recursos (memoria, conexiones, threads)
La respuesta debe incluir un header Retry-After.
504 Gateway Timeout
Un proxy o gateway no recibió respuesta de un servidor upstream dentro del período de timeout. A diferencia de 502 (respuesta inválida), 504 significa que ninguna respuesta llegó.
Troubleshooting de Errores HTTP
Identifique Dónde se Originó el Error
En sistemas distribuidos, los errores pueden ocurrir en múltiples capas:
Cliente → [CDN](/es/learning/cdn/que-es-una-cdn/)/Edge → [Load Balancer](/es/learning/performance/que-es-el-balanceo-de-carga/) → API Gateway → Aplicación → Base de Datos ↑ ↑ ↑ ↑ ↑ 403/502 502/503 502/504 4xx/5xx 502/504Para encontrar la causa raíz, verifique logs en cada capa. El código de estado que el cliente ve es el ÚLTIMO código generado a lo largo del camino.
Verifique Headers para Pistas
Server: Identifica qué software generó la respuestaX-Cache-Status: Estado de cache hit/miss del CDNX-Request-ID: ID de correlación para rastreo entre serviciosRetry-After: Cuándo reintentar (429, 503)WWW-Authenticate: Requisitos de autenticación (401)
Distinga 4xx de 5xx
| Tipo de Error | Quién Puede Corregir | Ejemplos |
|---|---|---|
| 4xx Error del Cliente | Cliente | URL incorrecta, auth ausente, cuerpo de solicitud inválido |
| 5xx Error del Servidor | Administrador del servidor | Crash del backend, sobrecarga, timeout, mala configuración |
Cuándo Usar Cada Código de Estado en Tu API
Operaciones Exitosas
200 OK: Éxito estándar paraGET,PATCH201 Created: Recurso creado viaPOST202 Accepted: Solicitud aceptada para procesamiento asíncrono204 No Content: Éxito sin cuerpo (DELETE, algunosPUT)
Errores del Cliente
400 Bad Request: Entrada inválida, sintaxis malformada401 Unauthorized: Autenticación ausente o inválida403 Forbidden: Autenticado pero no autorizado404 Not Found: Recurso no existe409 Conflict: Conflicto de estado (duplicado, versión incompatible)422 Unprocessable Entity: Sintaxis válida pero errores semánticos429 Too Many Requests: Límite de tasa excedido
Errores del Servidor
500 Internal Server Error: Fallo inesperado del servidor502 Bad Gateway: Upstream retornó respuesta inválida503 Service Unavailable: Sobrecarga temporal o mantenimiento504 Gateway Timeout: Upstream no respondió a tiempo
Métricas y Medición
Rastrea estas métricas para monitorear patrones de error HTTP:
- Tasa de error 5xx: Meta < 0,1% para servicios en producción
- Tasa de error 4xx: Monitorea picos indicando clientes con problemas
- Distribución de códigos de estado: Cambios repentinos indican problemas
- Presupuesto de error: Porcentaje de solicitudes fallidas permitidas por SLO
Referencias del mercado:
- 99,9% disponibilidad = 8,76 horas de downtime/año
- 99,99% disponibilidad = 52,56 minutos de downtime/año
- Principales causas de 5xx: bugs de deploy (40%), fallos de dependencia (30%), cambios de config (20%), capacidad (10%) (Google SRE)
Preguntas Frecuentes
¿Cuál es la diferencia entre 401 y 403? 401 significa “necesitas autenticarte”. 403 significa “estás autenticado pero no tienes permiso”.
¿Debo retornar 404 o 403 para recursos que el usuario no puede acceder? Retorna 404 si quieres esconder la existencia del recurso. Retorna 403 si el usuario debe saber que existe pero no puede accederlo.
¿Puedo crear códigos de estado personalizados? Sí, pero deben seguir la semántica de la clase (2xx para éxito, 4xx para errores del cliente, 5xx para errores del servidor). Registra códigos personalizados con IANA para APIs públicas.
¿Cómo manejan los CDNs los códigos de estado? Los CDNs hacen caché basado en el código de estado y Cache-Control. La mayoría de respuestas 4xx y 5xx no se cachean por defecto.
¿Qué código de estado deben retornar los webhooks? Retorna 200 OK para confirmar recepción. Retorna 202 Accepted para procesamiento asíncrono. Cualquier no-2xx activará reintentos del sistema enviador.
¿HTTP/2 y HTTP/3 cambian los códigos de estado? No. Los códigos de estado permanecen iguales entre versiones HTTP.
¿Mi API debe retornar 500 para errores de lógica de negocio? No. Usa códigos 4xx para condiciones de error esperadas. Reserva 500 para fallos técnicos inesperados.
¿Cuál es el código correcto para rate limiting? 429 Too Many Requests, con header Retry-After.