Guía completa de códigos de estado HTTP
Deja de adivinar qué significa 401 frente a 403: un recorrido para desarrolladores por cada familia de códigos con ejemplos realistas, anti‑patrones y los que realmente importan para SEO.
Más utilidades que combinan bien con esta guía:
Por qué importa
Un ingeniero backend devuelve 200 OK con {"error": "Unauthorized"} en el cuerpo. El manejador genérico del frontend lo trata como éxito porque el estado fue 200. El formulario de inicio de sesión entra en bucle. Pequeños errores de código de estado cuestan horas de ingeniería — y distorsionan rastreos SEO y reportes de enlaces rotos. Saber qué código enviar es parte del trabajo.
Tres escenarios reales
¿Falta token? 401. ¿Token sin permiso? 403. ¿El recurso no existe? 404.
Comportamiento predecible del cliente
301 conserva PageRank; 302 indica temporalidad sin transferencia. Elige con intención.
Redirección permanente con transferencia de ranking
503 con cabecera Retry-After indica a los rastreadores que vuelvan más tarde en lugar de desindexar.
Los buscadores saben reintentar
Las cinco familias de un vistazo
| Rango | Familia | Miembros habituales |
|---|---|---|
| 1xx | Informativos | 100 Continue, 101 Switching Protocols |
| 2xx | Éxito | 200 OK, 201 Created, 204 No Content |
| 3xx | Redirección | 301, 302, 304 Not Modified, 308 |
| 4xx | Error del cliente | 400, 401, 403, 404, 422, 429 |
| 5xx | Error del servidor | 500, 502, 503, 504 |
Guía paso a paso — usando la referencia
Abre la referencia de códigos HTTP.
Buscar por código o descripción
Escribe «401», «unauthorized» o «rate limit». Los códigos coincidentes suben al principio.
Leer el significado canónico
Cada entrada explica lo que dice la especificación, no solo lo que imprime curl.
Ver uso en el mundo real
Las notas indican dónde APIs populares (GitHub, Stripe, AWS) se desvían ligeramente.
Detectar impacto SEO
Cada código lleva etiqueta de tratamiento por buscadores (indexable / no, transfiere ranking / no).
Copiar una línea
Pega la descripción en tu documentación de API o comentario inline.
Escenario
POST /admin/users
(No Authorization header)Respuesta recomendada
401 Unauthorized
WWW-Authenticate: Bearer realm="admin"Escenario
POST /admin/users
Authorization: Bearer eyJ... (valid token, viewer scope)Respuesta recomendada
403 Forbidden
{"error": "scope_admin_required"}
Consejos útiles
- Usa 422 para entrada «bien formada pero semánticamente inválida» (p. ej. JSON con tipos de campo incorrectos). 400 es para peticiones mal formadas.
- 204 No Content en borrados es más claro que 200 con cuerpo vacío — indica que no hay payload a propósito.
- Incluye siempre
Retry-Aftercon 429 / 503. Los clientes inteligentes saben cuándo volver. - Evita 200 con
error: ...en el cuerpo. Anula el propósito de los códigos HTTP y confunde a herramientas de monitorización.
Trampas comunes
Error frecuente
Devolver 404 por «no puedes acceder a esto»
Un 404 vago oculta la existencia — a veces es lo deseado (p. ej. repos privados), pero en APIs autenticadas normales prefiere 403 para que el cliente sepa que el problema es de autorización.
Error frecuente
Cachear un 302 para siempre
302 es temporal por especificación, pero algunos intermediarios cachean agresivamente. Si la redirección es permanente, envía 301 (o 308 para conservar el método).
Error frecuente
Devolver 500 por errores del cliente
500 significa error del servidor. Si el cliente envió datos malos, devuelve 4xx — si no, tus alertas saltan por un bug en su código.
Cuándo no es la herramienta adecuada
- Diseñar un protocolo nuevo — los códigos HTTP están ligados a HTTP; gRPC, WebSockets y protocolos propios tienen sus propias convenciones.
- Informes de error dentro de la app — los códigos de aplicación van en el cuerpo junto al código HTTP.
- Monitorización — tu APM debería categorizar códigos automáticamente; esta referencia es para decisiones de diseño antes de desplegar.
Preguntas frecuentes
¿Diferencia entre 301 y 308?
Ambas son redirecciones permanentes. 308 garantiza que se conserva el método HTTP; 301 históricamente permitía que los clientes cambiaran POST → GET al seguir.
¿Es real el 418 «I'm a teapot»?
Sí, RFC 2324 (1 de abril de 1998), reafirmado en RFC 7168. Es una respuesta humorística no usada en APIs de producción.
¿Debo exponer códigos específicos del framework (p. ej. 419, 440)?
Evita códigos no estándar si puedes. Ceñete al conjunto registrado en IANA para que los clientes genéricos los entiendan.
Próximos pasos
- Inspecciona respuestas con el analizador de URL al depurar comportamiento extraño.
- Consulta comandos Git o Linux que ejecutes al hacer triaje en las referencias Git y Linux.
- Verifica IP/ASN del servidor subyacente con la herramienta de consulta IP cuando 502/504 apunten a problemas upstream.