Referencia de Códigos de Estado HTTP

La Referencia de Códigos de Estado HTTP es un índice completo con función de búsqueda de cada código de estado definido en las especificaciones de HTTP — desde 100 Continue hasta 511 Network Authentication Required. Cada entrada muestra el nombre canónico, la RFC que lo define, lo que el código realmente significa, cuándo enviarlo, cuándo no enviarlo y los errores comunes que afectan a las bases de código reales. Un filtro en vivo y botones de categoría le permiten saltar de una clase a otra con un solo clic.

A diferencia de una hoja de trucos convencional, esta herramienta le da a cada código su propia micropágina con tres paneles codificados por colores (qué hacer / qué no hacer / errores comunes) y manejadores listos para pegar para Express.js, Django, FastAPI y Go net/http. El diagrama de líneas animado muestra la solicitud viajando desde el cliente al servidor y el estado elegido fluyendo de regreso — útil para los principiantes que están aprendiendo lo que realmente representa un código de estado en la red.

Por qué es importante una referencia de códigos de estado

Cómo usar la Referencia de Códigos de Estado HTTP

1. Búsqueda rápida. Escriba un código (404) o un fragmento de nombre (teapot, gateway) en el cuadro de búsqueda en la parte superior y envíelo. La entrada coincidente se abrirá con el panel de detalles completo.
2. Examinar por clase. Haga clic en cualquiera de los 5 botones (1xx, 2xx, 3xx, 4xx, 5xx) para filtrar la cuadrícula a esa clase. Haga clic en Todos para restablecer.
3. Filtro en vivo. El cuadro de filtro justo encima de la cuadrícula reduce las tarjetas a medida que escribe — útil cuando recuerda la mitad de un nombre como too many o precondition.
4. Inspeccionar un código. Haga clic en cualquier tarjeta para abrir su panel de detalles. Verá el significado, cuándo usar, cuándo no usar, errores comunes y un bloque de fragmentos de código para 4 entornos de trabajo.
5. Copiar un fragmento de código. Use el selector de pestañas y el pequeño botón Copiar para obtener un manejador listo para pegar.
6. Comparar vecinos. El panel de detalles finaliza con tarjetas hermanas de la misma clase (1xx / 2xx / 3xx / 4xx / 5xx) para una comparación rápida lado a lado.

Las cinco clases de estado HTTP de un vistazo

Pares frecuentemente confundidos

• 401 frente a 403. 401 significa no autenticado — la solicitud carece de credenciales válidas. 403 significa autenticado pero no permitido — las credenciales son correctas pero el usuario carece de permiso.
• 404 frente a 410. 404 significa desconocido: tal vez exista en algún lugar, tal vez sea un error tipográfico. 410 significa eliminado deliberadamente: los motores de búsqueda deberían eliminarlo del índice.
• 301 frente a 302 frente a 307 frente a 308. 301 / 308 son permanentes (308 conserva estrictamente el método y el cuerpo), 302 / 307 son temporales (307 conserva estrictamente el método y el cuerpo). Use 307 / 308 para redirecciones de POST / PUT / PATCH.
• 400 frente a 422. 400 significa que el cuerpo de la solicitud está malformado (mal JSON, campo faltante). 422 significa que el cuerpo se analizó correctamente pero los valores fallan en las reglas de negocio (formato de correo electrónico no válido, cantidad fuera de rango).
• 502 frente a 503 frente a 504. 502 significa que el servidor ascendente envió basura. 503 significa que el servidor está sobrecargado o en mantenimiento. 504 significa que el servidor ascendente no respondió a tiempo.
• 409 frente a 412. 409 es un conflicto con el estado actual del recurso. 412 significa específicamente que un encabezado de condición previa (If-Match, If-Unmodified-Since) se evaluó como falso.

Encabezados que se emparejan con códigos de estado específicos

• 201 Created — debería incluir Location apuntando al nuevo recurso.
• 301 / 302 / 307 / 308 — debe incluir Location con la URL de destino.
• 304 Not Modified — debe reflejar los encabezados que habrían aparecido en un 200 (ETag, Cache-Control, Vary).
• 401 Unauthorized — debe incluir WWW-Authenticate enumerando los esquemas aceptados (Basic, Bearer).
• 405 Method Not Allowed — debe incluir Allow enumerando los métodos que sí están permitidos.
• 413 / 429 / 503 — a menudo incluyen Retry-After (segundos o HTTP-date) para que los clientes se retiren correctamente.
• 416 Range Not Satisfiable — debe incluir Content-Range: bytes */<length>.

Códigos de estado que casi siempre puede ignorar

Un puñado de códigos son técnicamente válidos pero extremadamente raros en las API modernas: 305 Use Proxy (depreciado), 306 (reservado, no utilizado), 305, 506 Variant Also Negotiates, 510 Not Extended y 508 Loop Detected. La mayoría se mantienen en el registro por razones históricas. Si su biblioteca o middleware emite uno de ellos, trátelo como un informe de error contra la biblioteca — no como una sugerencia para manejarlo de manera especial.

Preguntas frecuentes

¿Incluye la herramienta códigos de otras RFC que no sean la 9110?

Sí. Cubre la RFC 9110 (semántica HTTP), RFC 6585 (4xx / 5xx adicionales), RFC 4918 (WebDAV), RFC 5842 (enlaces WebDAV), RFC 7725 (451), RFC 8297 (103 Early Hints), RFC 8470 (425 Too Early) y la famosamente lúdica RFC 2324 (418 Teapot).

¿Son válidos estos códigos en HTTP/2 y HTTP/3?

Sí. La semántica de los códigos de estado está definida en la RFC 9110, que es el documento de semántica HTTP independiente de la versión. HTTP/2 (RFC 9113) y HTTP/3 (RFC 9114) solo cambian el entramado y el transporte.

¿Puedo enlazar directamente a un código específico?

Envíe el formulario con un solo código (por ejemplo 404) y el panel de detalles se cargará debajo del formulario. La URL muestra su búsqueda y es segura para compartir — al abrirla se carga el mismo resultado.

¿Por qué mi entorno de trabajo no me permite devolver el 418?

Las versiones anteriores de algunas bibliotecas HTTP se niegan a emitir códigos que no están en su registro interno. La solución es actualizar la biblioteca o, cuando sea posible, escribir la línea de estado manualmente.

¿Debería una API devolver alguna vez 200 con un cuerpo de error?

No. El monitoreo, los reintentos y los intermediarios asumen que 2xx significa éxito. Si debe devolver una estructura de error, devuelva un 4xx o 5xx apropiado y coloque el detalle estructurado dentro del cuerpo. El formato Problem Details for HTTP APIs (RFC 9457) es una buena plantilla.

¿Existe un registro oficial de códigos de estado HTTP?

Sí. IANA mantiene el registro en iana.org/assignments/http-status-codes. Esta herramienta se mantiene sincronizada con ese registro además de las RFC más comúnmente citadas.