Códigos de Estado HTTP: Guía de Referencia Completa
· 12 min de lectura
Tabla de Contenidos
- ¿Qué Son los Códigos de Estado HTTP?
- Cómo Funcionan los Códigos de Estado
- 1xx Informativo
- 2xx Éxito
- 3xx Redirección
- 4xx Errores del Cliente
- 5xx Errores del Servidor
- Solución de Errores Comunes
- Mejores Prácticas para Desarrolladores
- Prueba y Depuración de Códigos de Estado
- Preguntas Frecuentes
- Artículos Relacionados
¿Qué Son los Códigos de Estado HTTP?
Los códigos de estado HTTP son números de tres dígitos devueltos por un servidor en respuesta a la solicitud de un cliente. Indican si la solicitud fue exitosa, redirigida o resultó en un error. Cada vez que tu navegador carga una página, llama a una API o envía un formulario, el servidor responde con un código de estado.
Piensa en los códigos de estado como la forma en que el servidor comunica lo que sucedió con tu solicitud. Así como un semáforo te indica si debes detenerte o avanzar, los códigos de estado le indican a tu aplicación si debe continuar, reintentar o manejar un error.
Los códigos de estado se agrupan en cinco categorías según su primer dígito:
- 1xx (Informativo): Solicitud recibida, el procesamiento continúa
- 2xx (Éxito): Solicitud recibida, comprendida y aceptada
- 3xx (Redirección): Se necesita una acción adicional para completar la solicitud
- 4xx (Error del Cliente): La solicitud contiene un error del lado del cliente
- 5xx (Error del Servidor): El servidor no pudo cumplir una solicitud válida
Referencia rápida: Usa nuestra herramienta de Búsqueda de Códigos de Estado HTTP para verificar rápidamente cualquier código de estado y ver explicaciones detalladas con ejemplos.
Cómo Funcionan los Códigos de Estado
Cuando un cliente (como tu navegador o un cliente API) realiza una solicitud HTTP, el servidor la procesa y devuelve una respuesta. Esta respuesta siempre incluye un código de estado en la primera línea, seguido de encabezados y un cuerpo opcional.
Así es como se ve una respuesta HTTP típica:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1234
{"status": "success", "data": {...}}El código de estado aparece justo después de la versión HTTP. En este ejemplo, 200 OK le indica al cliente que la solicitud fue exitosa.
Los códigos de estado sirven para múltiples propósitos:
- Comunicación: Proporcionan una forma estandarizada para que los servidores comuniquen resultados
- Manejo de errores: Las aplicaciones pueden manejar programáticamente diferentes escenarios según el código
- Depuración: Los desarrolladores pueden identificar rápidamente dónde ocurren los problemas en el ciclo solicitud-respuesta
- SEO: Los motores de búsqueda usan códigos de estado para entender cómo indexar el contenido
- Almacenamiento en caché: Los navegadores y CDN usan códigos para determinar el comportamiento de caché
1xx Informativo
Los códigos de estado informativos indican que el servidor ha recibido la solicitud y continúa procesándola. Estas son respuestas provisionales y rara vez se ven en la navegación web cotidiana, pero son importantes para ciertos protocolos y optimizaciones.
100 Continue
El servidor recibió los encabezados de la solicitud y el cliente debe proceder a enviar el cuerpo. Esto se usa con cargas grandes donde el cliente envía un encabezado Expect: 100-continue para verificar si el servidor aceptará la solicitud antes de enviar la carga completa.
Esta optimización evita desperdiciar ancho de banda en solicitudes que serán rechazadas. Por ejemplo, si estás subiendo un archivo de video de 500MB, no quieres enviar todos esos datos solo para descubrir que el servidor lo rechazará debido a un fallo de autenticación.
POST /upload HTTP/1.1
Host: api.example.com
Content-Length: 524288000
Expect: 100-continue
// El servidor responde con 100 Continue
// El cliente luego envía el cuerpo de la solicitud101 Switching Protocols
El servidor acepta cambiar de protocolo según lo solicitado por el cliente. Se ve más comúnmente al actualizar de HTTP a WebSocket usando el encabezado Upgrade: websocket.
Los WebSockets permiten comunicación bidireccional en tiempo real entre cliente y servidor, lo cual es esencial para aplicaciones de chat, actualizaciones en vivo y herramientas colaborativas.
GET /chat HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
// El servidor responde con 101 Switching Protocols103 Early Hints
Este código de estado relativamente nuevo permite al servidor enviar encabezados preliminares antes de la respuesta final. A menudo se usa para comenzar a precargar recursos como CSS, fuentes y archivos JavaScript mientras el servidor aún está preparando la respuesta principal.
Early Hints puede mejorar significativamente los tiempos de carga de página al permitir que los navegadores comiencen a descargar recursos críticos más temprano en el proceso de carga de la página.
Consejo profesional: La mayoría de los desarrolladores nunca necesitarán manejar códigos 1xx directamente. Generalmente son administrados por servidores web y bibliotecas HTTP automáticamente. Enfoca tu manejo de errores en códigos 4xx y 5xx en su lugar.
2xx Éxito
Los códigos de éxito son lo que quieres ver. Indican que la solicitud fue recibida, comprendida y aceptada exitosamente. Diferentes códigos 2xx proporcionan información matizada sobre exactamente cómo se procesó la solicitud.
200 OK
La respuesta de éxito estándar. La solicitud fue exitosa y el cuerpo de la respuesta contiene los datos solicitados. Este es el código de estado más común en la web.
Usa 200 OK para solicitudes GET exitosas que devuelven datos, solicitudes POST exitosas que devuelven datos del recurso creado, y solicitudes PUT/PATCH exitosas que devuelven datos del recurso actualizado.
GET /api/users/123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{"id": 123, "name": "John Doe", "email": "[email protected]"}201 Created
Se creó exitosamente un nuevo recurso. Esta es la respuesta apropiada para solicitudes POST que crean nuevos recursos. La respuesta debe incluir un encabezado Location que apunte al recurso recién creado.
POST /api/users HTTP/1.1
Content-Type: application/json
{"name": "Jane Smith", "email": "[email protected]"}
HTTP/1.1 201 Created
Location: /api/users/124
Content-Type: application/json
{"id": 124, "name": "Jane Smith", "email": "[email protected]"}202 Accepted
La solicitud ha sido aceptada para procesamiento, pero el procesamiento no se ha completado. Esto es útil para operaciones asíncronas donde el servidor pone en cola la solicitud para procesamiento posterior.
Los casos de uso comunes incluyen procesamiento por lotes, envío de correos electrónicos, codificación de video y otras operaciones de larga duración que no deberían bloquear la respuesta HTTP.
204 No Content
La solicitud fue exitosa, pero no hay contenido para devolver. Esto se usa comúnmente para solicitudes DELETE o solicitudes PUT/PATCH donde el cliente no necesita que se devuelva el recurso actualizado.
Usar 204 No Content en lugar de 200 OK con un cuerpo vacío ahorra ancho de banda y comunica claramente la intención.
DELETE /api/users/123 HTTP/1.1
HTTP/1.1 204 No Content206 Partial Content
El servidor está entregando solo parte del recurso debido a un encabezado de rango enviado por el cliente. Esto permite descargas reanudables y transmisión de video donde el cliente solicita rangos de bytes específicos.
Los reproductores de video usan esto extensivamente para permitir buscar diferentes partes de un video sin descargar primero el archivo completo.
| Código de Estado | Nombre | Cuándo Usar |
|---|---|---|
200 |
OK | Respuesta de éxito estándar con contenido |
201 |
Created | Recurso creado exitosamente |
202 |
Accepted | Solicitud en cola para procesamiento asíncrono |
204 |
No Content | Éxito sin necesidad de cuerpo de respuesta |
206 |
Partial Content | Devolviendo rango de bytes solicitado |
3xx Redirección
Los códigos de redirección indican que el cliente necesita tomar una acción adicional para completar la solicitud. Estos son cruciales para la gestión de URL, SEO y mantener la compatibilidad hacia atrás cuando los recursos se mueven.
301 Moved Permanently
El recurso se ha movido permanentemente a una nueva URL especificada en el encabezado Location. Los navegadores y motores de búsqueda deben actualizar sus registros para usar la nueva URL.
Este es el código de estado preferido para redirecciones permanentes. Los motores de búsqueda transferirán el valor SEO de la URL antigua a la nueva, y los navegadores almacenarán en caché la redirección.
GET /old-page HTTP/1.1
HTTP/1.1 301 Moved Permanently
Location: https://example.com/new-pageConsejo profesional: Usa redirecciones 301 cuando hayas movido contenido permanentemente. Usa 302 para movimientos temporales. Equivocarse en esto puede perjudicar tu SEO, ya que los motores de búsqueda los tratan de manera muy diferente.
302 Found (Redirección Temporal)
El recurso reside temporalmente en una URL diferente. El cliente debe continuar usando la URL original para solicitudes futuras. Los motores de búsqueda no transferirán valor SEO con esta redirección.
Los casos de uso comunes incluyen pruebas A/B, páginas de mantenimiento y páginas promocionales temporales.
303 See Other
La respuesta a la solicitud se puede encontrar en otra URL usando GET. Esto se usa comúnmente después de solicitudes POST para redirigir a una página de resultados, evitando envíos de formularios duplicados si el usuario actualiza.
Esto implementa el patrón Post/Redirect/Get, que es una mejor práctica para formularios web.
304 Not Modified
El recurso no ha sido modificado desde la versión especificada en los encabezados de la solicitud (If-Modified-Since o If-None-Match). El cliente puede usar su versión en caché.
Esto reduce dramáticamente el uso de ancho de banda y mejora el rendimiento al evitar transferencias de datos innecesarias cuando el contenido no ha cambiado.
307 Temporary Redirect
Similar a 302, pero garantiza que el método de solicitud no cambiará cuando se redirija. Si la solicitud original fue POST, la solicitud redirigida también será POST.
308 Permanent Redirect
Similar a 301, pero garantiza que el método de solicitud no cambiará. Esta es la versión moderna y más precisa de 301 para APIs y aplicaciones que necesitan preservación estricta del método.
4xx Errores del Cliente
Los códigos de error del cliente indican que la solicitud contiene sintaxis incorrecta o no puede cumplirse debido a problemas del lado del cliente. Estos errores significan que el cliente necesita modificar la solicitud antes de reintentar.
400 Bad Request
El servidor no puede procesar la solicitud debido a sintaxis mal formada, encuadre de mensaje de solicitud inválido o enrutamiento de solicitud engañoso. Este es un error genérico para solicitudes que no encajan en otras categorías 4xx.
Las causas comunes incluyen JSON mal formado, campos requeridos faltantes, tipos de datos inválidos o solicitudes que violan restricciones de API.
POST /api/users HTTP/1.1
Content-Type: application/json
{"name": "John", "email": "not-an-email"}
HTTP/1.1 400 Bad Request
Content-Type: application/json
{"error": "Invalid email format"}401 Unauthorized
Se requiere autenticación y ha fallado o no se ha proporcionado. A pesar del nombre, esto en realidad significa "no autenticado" – el cliente necesita proporcionar credenciales válidas.
La respuesta debe incluir un encabezado WWW-Authenticate indicando el método de autenticación requerido.
GET /api/protected-resource HTTP/1.1
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"
{"error": "Authentication required"}403 Forbidden
El servidor entendió la solicitud pero se niega a autorizarla. A diferencia de 401, la autenticación no ayudará – el cliente no tiene permiso para acceder a este recurso.
Usa esto cuando un usuario está autenticado pero no tiene los permisos necesarios, o cuando el acceso está restringido por dirección IP, limitación de tasa u otras políticas.