Referencia de códigos de estado HTTP
Los códigos de estado HTTP que realmente aparecen en el desarrollo web, organizados por clase: para diseñar APIs, depurar y gestionar errores.
Qué es un código de estado HTTP
Un código de estado HTTP es el número de tres cifras con el que el servidor describe el resultado de una petición del cliente (un navegador o un cliente de API). El primer dígito fija la categoría, dando cinco clases de 1xx a 5xx. Devolver el código correcto es fundamental al diseñar una API RESTful.
1xx — Informativas
La petición se recibió y el procesamiento continúa. Los navegadores las gestionan automáticamente, así que rara vez se tratan a mano.
| Código | Nombre | Significado |
|---|---|---|
100 | Continue | Se recibió la primera parte de la petición; el cliente puede continuar |
101 | Switching Protocols | Cambio de protocolo aceptado; se usa al establecer una conexión WebSocket |
103 | Early Hints | Una pista para que el cliente empiece a precargar recursos antes de la respuesta final |
2xx — Éxito
La petición se aceptó y se procesó. Es la clase que más se usa al desarrollar APIs.
| Código | Nombre | Significado | Uso habitual |
|---|---|---|---|
200 | OK | Petición correcta | GET, PUT o PATCH correctos |
201 | Created | Petición correcta y se creó un recurso nuevo | Un POST que creó un recurso |
202 | Accepted | Petición aceptada pero aún sin procesar | Al aceptar un trabajo asíncrono |
204 | No Content | Petición correcta sin contenido que devolver | Un DELETE correcto, o un PUT que solo actualiza |
206 | Partial Content | Respuesta parcial a una petición de rango | Al reanudar la descarga de un archivo grande |
3xx — Redirección
Hace falta una acción adicional para completar la petición, normalmente seguir una redirección. Son clave para el SEO y las migraciones de URL.
| Código | Nombre | Significado | Uso habitual |
|---|---|---|---|
301 | Moved Permanently | El recurso se movió de forma permanente | Cambios de URL y migraciones de dominio; transmite las señales SEO |
302 | Found | Redirigido temporalmente a otra URL | Un traslado temporal durante el mantenimiento |
303 | See Other | Consultar otra URL con GET | Redirección tras un POST (patrón PRG) |
304 | Not Modified | El recurso no ha cambiado | Usa la caché del navegador y ahorra ancho de banda |
307 | Temporary Redirect | Redirección temporal que conserva el método | Un traslado temporal de HTTP a HTTPS |
308 | Permanent Redirect | Redirección permanente que conserva el método | Traslado permanente de un endpoint de API |
4xx — Error del cliente
El problema está en el cliente, normalmente el contenido de la petición o las credenciales.
| Código | Nombre | Significado | Uso habitual |
|---|---|---|---|
400 | Bad Request | La sintaxis de la petición no es válida | Errores de validación, JSON mal formado |
401 | Unauthorized | Se requiere autenticación | Sin sesión iniciada o token caducado |
403 | Forbidden | Sin permiso de acceso | Autenticado pero sin acceso al recurso |
404 | Not Found | No se encontró el recurso | Una URL inexistente o un recurso eliminado |
405 | Method Not Allowed | Método HTTP no permitido | Enviar POST a un endpoint solo de GET |
408 | Request Timeout | La petición agotó el tiempo de espera | Cuando el cliente envía los datos demasiado despacio |
409 | Conflict | Conflicto de recursos | Registros duplicados, colisiones de bloqueo optimista |
413 | Payload Too Large | El cuerpo de la petición es demasiado grande | Se superó el límite de subida |
415 | Unsupported Media Type | Tipo de medio no admitido | Un Content-Type incorrecto |
422 | Unprocessable Entity | Sintaxis correcta pero imposible de procesar semánticamente | Errores de validación (detallados) |
429 | Too Many Requests | Se superó el límite de peticiones | Cuotas de llamadas a la API |
5xx — Error del servidor
El procesamiento falló en el servidor, normalmente por un error de configuración o un fallo de la aplicación.
| Código | Nombre | Significado | Uso habitual |
|---|---|---|---|
500 | Internal Server Error | Error interno del servidor | Excepciones no capturadas, fallos de la aplicación |
501 | Not Implemented | El servidor no admite la funcionalidad | Un endpoint de API aún sin implementar |
502 | Bad Gateway | La pasarela recibió una respuesta no válida | El servidor upstream tras el proxy inverso no responde |
503 | Service Unavailable | Servicio no disponible | En mantenimiento o sobrecargado |
504 | Gateway Timeout | Tiempo de espera de la pasarela agotado | El servidor upstream no respondió a tiempo |
Preguntas frecuentes
¿Cuál es la diferencia entre 401 y 403?
401 Unauthorized indica que hace falta autenticarse e invita a iniciar sesión o presentar un token. 403 Forbidden indica que el cliente está autenticado pero no tiene permiso sobre el recurso. Un usuario normal que entra en una página solo de administradores debe recibir un 403.
¿Cuál es la diferencia entre 301 y 308?
Ambas son redirecciones permanentes, pero con 301 el método HTTP puede reescribirse a GET por el camino. 308 reenvía la petición conservando el método. Usa 308 cuando un POST deba seguir siendo POST en el destino.
¿Qué hago ante un error 413?
Cuando una subida devuelve 413 Payload Too Large, revisa los límites de cada capa: el servidor web (client_max_body_size en Nginx, LimitRequestBody en Apache) y PHP (upload_max_filesize, post_max_size). Los archivos de prueba de umbral de DevLab permiten confirmar el límite real.