Códigos de estado HTTP
Códigos que más ves en APIs y CDN. Se omiten los experimentales raros.
| Código | Nombre | Significado |
|---|---|---|
| 200 | OK | Éxito con cuerpo |
| 201 | Creado | Recurso creado |
| 204 | Sin contenido | Éxito, cuerpo vacío |
| 301 | Movido permanentemente | Redirección permanente |
| 302 | Encontrado | Redirección temporal |
| 304 | No modificado | Usar copia en caché |
| 400 | Solicitud incorrecta | Solicitud del cliente inválida |
| 401 | No autorizado | Autenticación requerida o fallida |
| 403 | Prohibido | Autenticado pero denegado |
| 404 | No encontrado | El recurso no existe |
| 405 | Método no permitido | Método HTTP incorrecto |
| 408 | Tiempo de espera agotado | Cliente demasiado lento |
| 409 | Conflicto | Conflicto de estado |
| 410 | Desaparecido | Eliminado permanentemente |
| 422 | Entidad no procesable | Semántica inválida |
| 429 | Demasiadas solicitudes | Límite de peticiones |
| 500 | Error interno del servidor | Fallo del servidor |
| 502 | Puerta de enlace incorrecta | Respuesta upstream inválida |
| 503 | Servicio no disponible | Sobrecargado o caído |
| 504 | Tiempo de espera de la puerta de enlace agotado | Tiempo de espera del upstream agotado |
Notas
- 401 vs 403: credenciales fallidas o ausentes frente a autenticado sin permiso.
- El CDN puede devolver 5xx si el origen no responde.
Las cinco clases de códigos de estado
El primer dígito te indica quién es el responsable y, aproximadamente, qué sucedió. 1xx son informativos y raramente los ven los clientes. 2xx indican éxito — 200 OK con cuerpo, 204 No Content sin él, 206 para descarga parcial. 3xx indican que el recurso está en otro lugar. 4xx indican que la solicitud en sí es incorrecta: sintaxis mala, credenciales faltantes o límite de tasa. 5xx indican que el servidor falló aunque la solicitud estaba bien. Leer solo el primer dígito ya te dice si debes arreglar el cliente o escalar al lado del servidor.
Elegir la redirección adecuada
301 y 308 significan ambos permanente; 302 y 307 significan ambos temporal. La diferencia es cómo se maneja el método: 301 y 302 históricamente permitían a los clientes convertir un POST en GET, mientras que 307 y 308 preservan el método original y el cuerpo, lo cual importa para APIs y envíos de formularios. Usa 301 para una URL que se ha movido permanentemente, y 302 o 307 para enrutamiento temporal como páginas de mantenimiento o pruebas A/B. Cuidado con las cadenas: cada salto extra cuesta latencia y prestigio de enlace, así que redirige directamente al destino final.
Ordenando los errores 4xx
401 significa que falta o falló la autenticación, por lo que enviar credenciales válidas puede resolverlo; 403 significa que la solicitud fue entendida y autenticada pero no se permite, y reintentar con las mismas credenciales no ayudará. 404 significa que el recurso no existe; 410 indica que existía y está deliberadamente eliminado. 429 significa que alcanzaste un límite de tasa y debes retroceder, respetando cualquier encabezado Retry-After. 400 generalmente significa entrada malformada, 405 significa que el método es incorrecto para esa URL, y 422 significa que la sintaxis era válida pero el contenido falló la validación.
Leyendo los códigos 5xx
500 es un error interno genérico; 502 Bad Gateway significa que un servidor upstream devolvió algo inutilizable; 503 significa que el servicio está temporalmente no disponible o sobrecargado; 504 significa que un servidor upstream agotó el tiempo de espera. Estos son problemas del servidor, no del llamante, así que la solución es reintentar con retroceso, verificar la salud del servidor upstream o reducir la carga. Una CDN puede emitir 502, 503 o 504 en nombre de un origen al que no puede acceder, lo cual explica por qué el mismo error puede provenir de dos lugares muy diferentes: verifica los encabezados server y cache-status para averiguar cuál.
Códigos de estado en la práctica: APIs y caché
Dos usos cotidianos merecen atención. Primero, caché: 200 con un encabezado Cache-Control puede almacenarse, 304 Not Modified indica al cliente que reutilice su copia, y un 5xx no debe cachearse. Segundo, APIs: un POST que crea un recurso debe devolver 201 con un encabezado Location, DELETE suele devolver 204, y un PATCH que no cambia nada puede devolver 200 o 204. Los clientes bien comportados deciden primero según la clase (2xx, 4xx, 5xx) y solo después según el código exacto, lo que mantiene la lógica de reintento y retroceso simple y predecible.
Preguntas frecuentes
- ¿Qué significa el código HTTP 403?
- 403 Forbidden significa que el servidor entendió y autenticó la petición, pero rechaza dar acceso al recurso. A diferencia del 401, volver a iniciar sesión no lo soluciona.
- ¿Cuál es la diferencia entre las redirecciones HTTP 301 y 302?
- 301 indica un traslado permanente: clientes y buscadores deben usar la nueva URL. 302 es una redirección temporal y la URL original sigue siendo válida.
- ¿Qué significa HTTP 429 y cómo se soluciona?
- 429 significa que has superado un límite de peticiones. Reduce la frecuencia y respeta la cabecera Retry-After si el servidor la envía.