Códigos de estado HTTP

Un código de estado HTTP es un número de tres cifras enviado por el servidor como parte de la respuesta a una petición. Permite indicar de forma estandarizada el resultado de esa petición.

HTTP/1.1 200 OK

En este ejemplo, 200es el código de estado y OKes una frase descriptiva asociada al código.

La primera cifra identifica la clase general de respuesta:

1xx Información
2xx Éxito
3xx Redirección
4xx Error asociado a la solicitud del cliente
5xx Error del servidor

El código debe interpretarse junto con el método utilizado, las cabeceras, el cuerpo de la respuesta y el contexto de la operación.

Las respuestas de la clase 1xxson informativas. Indican un estado provisional de la comunicación antes de que llegue una respuesta final.

100 Continue
101 Switching Protocols

No suelen ser los códigos con los que más trabaja directamente una aplicación cliente, pero forman parte del protocolo y aparecen en determinados flujos HTTP.

101 Switching Protocolsindica que el servidor acepta cambiar el protocolo de comunicación de acuerdo con la negociación realizada en la petición.

Es un código relacionado con mecanismos de actualización del protocolo y no representa una respuesta de contenido convencional.

200 OKindica que la petición se ha procesado satisfactoriamente. Su significado concreto depende del método HTTP.

GET /api/usuarios/42→200 OK

En una petición GET, la respuesta suele incluir una representación del recurso solicitado cuando corresponde.

202 Acceptedindica que la petición ha sido aceptada para su procesamiento, pero que dicho procesamiento todavía no tiene por qué haberse completado.

Petición
↓
202 Accepted
↓
Procesamiento posterior

Es útil para operaciones asíncronas o tareas que no pueden completarse durante la misma interacción HTTP.

Los códigos 3xxindican que debe realizarse alguna acción adicional para completar la interacción. Muchos están relacionados con redirecciones y otros con mecanismos de caché.

301 Moved Permanently
302 Found
303 See Other
304 Not Modified
307 Temporary Redirect
308 Permanent Redirect

Los códigos de esta familia no son intercambiables. Las diferencias afectan, entre otras cosas, a la permanencia de la redirección y al tratamiento del método HTTP.

302 Foundindica que el recurso se encuentra temporalmente en otra URI.

Su comportamiento histórico en clientes web hace importante distinguirlo de códigos como 307cuando se necesita preservar de forma explícita el método de la petición.

307 Temporary Redirecty 308 Permanent Redirectpermiten expresar redirecciones manteniendo el método de la petición.

307 Temporary Redirect
308 Permanent Redirect

La diferencia principal entre ambos es que 307expresa una situación temporal y 308una permanente.

400 Bad Requestindica que el servidor no puede o no desea procesar la petición debido a un problema percibido en la solicitud.

Puede utilizarse, según el diseño de la aplicación, cuando la petición presenta sintaxis incorrecta, datos mal formados u otras condiciones que impiden interpretarla adecuadamente.

403 Forbiddenindica que el servidor comprende la petición pero rechaza atenderla.

Petición comprendida
↓
Acceso rechazado
↓
403 Forbidden

Autenticarse de nuevo no implica necesariamente que el acceso vaya a ser permitido.

405 Method Not Allowedindica que el servidor conoce el método utilizado pero el recurso de destino no lo admite.

DELETE /recurso→405 Method Not Allowed

La respuesta debe indicar mediante la cabecera Allowlos métodos admitidos para el recurso.

415 Unsupported Media Typeindica que el servidor rechaza la petición porque el formato del contenido no es compatible con la operación solicitada.

Content-Type: formato no admitido
↓
415 Unsupported Media Type

En APIs es especialmente importante enviar un Content-Typecoherente con el cuerpo transmitido.

429 Too Many Requestsindica que el cliente ha enviado demasiadas peticiones dentro de un periodo determinado.

Demasiadas peticiones
↓
429 Too Many Requests

Puede utilizarse en mecanismos de limitación de tasa. La respuesta puede incluir información que ayude al cliente a determinar cuándo volver a intentarlo.

500 Internal Server Errorrepresenta una condición inesperada que impide al servidor completar la petición.

Petición válida
↓
Fallo inesperado en el servidor
↓
500 Internal Server Error

Es un código genérico y no debería utilizarse para ocultar sistemáticamente condiciones que pueden describirse mediante códigos más específicos.

503 Service Unavailableindica que el servidor no puede atender temporalmente la petición.

Puede relacionarse, por ejemplo, con una sobrecarga temporal o una operación de mantenimiento.

Cuando sea posible, la respuesta puede incluir información sobre el momento apropiado para volver a intentarlo.

401y 403suelen confundirse, pero expresan situaciones diferentes.

401 Unauthorized
Autenticación necesaria o no válida

403 Forbidden
Petición comprendida, acceso rechazado

La elección debe basarse en la situación real y en la semántica definida por HTTP, no únicamente en el texto descriptivo del código.

Una API debe escoger el código según el resultado real de la operación y mantener una semántica coherente entre endpoints.

GET /recursos/42 → 200 OK
POST /recursos → 201 Created
DELETE /recursos/42 → 204 No Content

Ante resultados diferentes podrían aparecer, por ejemplo:

GET /recursos/999 → 404 Not Found
POST /recursos → 400 Bad Request
GET /privado → 401 Unauthorized
GET /restringido → 403 Forbidden

Estos ejemplos muestran relaciones habituales, no una regla automática aplicable a cualquier API. El diseño concreto debe respetar la semántica HTTP y las condiciones reales de cada operación.

Para interpretar correctamente una respuesta HTTP puede ser necesario examinar también sus cabeceras.

Location
Allow
Content-Type
Retry-After
WWW-Authenticate

Por ejemplo, una redirección puede utilizar Location, un 405se relaciona con Allowy determinadas respuestas de autenticación incluyen información adicional mediante WWW-Authenticate.

• Interpretar 401simplemente como «sin permisos» sin considerar su relación con la autenticación.
• Interpretar 403como equivalente a 401.
• Suponer que 404significa que el servidor está caído.
• Utilizar 200 OKpara cualquier respuesta, incluso cuando la operación ha fallado.
• Utilizar 500para errores que realmente pertenecen a la petición o tienen un código más específico.
• Considerar todos los códigos 3xxequivalentes.
• Analizar únicamente el cuerpo de una API e ignorar el código HTTP.
• Elegir un código por su nombre informal sin comprobar su semántica.

Cuando curlestá disponible, puede utilizarse para inspeccionar respuestas HTTP desde la terminal.

curl -I https://example.com

También puede mostrarse información de cabeceras durante una petición:

curl -i https://example.com

Las opciones disponibles dependen de la versión instalada. Puedes consultar también la ficha de comandos Linuxpara otras operaciones habituales de terminal.

• La primera cifra identifica la familia general de la respuesta.
• Un código debe elegirse por su semántica, no únicamente por su nombre.
• 2xxcontiene diferentes tipos de resultados satisfactorios.
• 3xxincluye comportamientos distintos relacionados con redirección y caché.
• 401y 403no son equivalentes.
• Un 404es una respuesta HTTP y no demuestra que el servidor esté caído.
• Los códigos 5xxindican problemas al completar la petición desde el lado servidor.
• El código debe interpretarse junto con el método, las cabeceras y el cuerpo de la respuesta.

Documentación primaria y referencias reconocidas para consultar la semántica de HTTP y los códigos de estado.

• RFC 9110 · HTTP Semantics
• Códigos de estado HTTP · MDN