Códigos de estado HTTP explicados: las 5 clases y los códigos que más se usan

Dónde aparece el código de estado

Es lo primero que envía el servidor, en la línea de estado, antes de las cabeceras y del cuerpo:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/pedidos/1042

{"id": 1042, "estado": "pendiente"}

El texto que acompaña al número (Created, Not Found) es solo orientativo. En HTTP/2 y HTTP/3 ni siquiera se envía; los clientes deben decidir por el número. Por eso cambiar el texto no cambia el significado, y un 200 Error sigue siendo un éxito para cualquier programa.

Para verlo: en el navegador, abre las herramientas de desarrollo (F12) y mira la columna Status de la pestaña Red. En la terminal, curl -I https://ejemplo.com muestra la línea de estado y las cabeceras, y curl -s -o /dev/null -w '%{http_code}' URL imprime solo el número.

Las cinco clases

El primer dígito define la clase, y es lo que un cliente debe entender aunque no conozca el código concreto. RFC 9110 establece que un código desconocido se trata como el x00 de su clase: un 299 desconocido se comporta como 200, y un 499 como 400.

1xx  Informativo   la petición sigue en curso         100 Continue, 101 Switching Protocols, 103 Early Hints
2xx  Éxito         la petición funcionó               200, 201, 202, 204, 206
3xx  Redirección   hace falta otra acción o URL       301, 302, 303, 304, 307, 308
4xx  Error cliente la petición es incorrecta          400, 401, 403, 404, 409, 422, 429
5xx  Error servidor el servidor falló                 500, 502, 503, 504

2xx: éxito

200 OK es la respuesta estándar con contenido. 201 Created indica que se creó un recurso; lo correcto es acompañarlo de una cabecera Location con la URL del recurso nuevo. 202 Accepted significa que la petición se aceptó pero se procesará después, por ejemplo en una cola, y el cliente deberá consultar el resultado más tarde.

204 No Content es un éxito sin cuerpo, típico tras un DELETE o un PUT que no devuelve nada. Un cliente que intenta parsear JSON en un 204 falla, así que compruébalo antes. 206 Partial Content responde a peticiones con cabecera Range: descargas reanudables y reproducción de vídeo.

3xx: redirecciones y caché

301 Moved Permanently y 308 Permanent Redirect indican que el recurso se movió para siempre; los buscadores trasladan el posicionamiento a la URL nueva. 302 Found y 307 Temporary Redirect son temporales. La diferencia entre cada pareja es el método: con 301 y 302 los navegadores convierten un POST en GET, mientras que 307 y 308 conservan el método y el cuerpo. 303 See Other se usa tras enviar un formulario para redirigir a una página de resultado con GET.

304 Not Modified no es una redirección real. Es la respuesta a una petición condicional (If-None-Match con un ETag, o If-Modified-Since) que indica que la copia en caché sigue siendo válida. No tiene cuerpo y ahorra transferir de nuevo el recurso.

4xx: errores del cliente

400 Bad Request: la petición está mal formada, por ejemplo con JSON inválido o parámetros ilegibles. 401 Unauthorized: falta autenticación o no es válida. 403 Forbidden: autenticado, pero sin permiso. 404 Not Found: no existe nada en esa URL. 405 Method Not Allowed: la ruta existe pero no acepta ese método; debe incluir la cabecera Allow con los métodos válidos.

409 Conflict: la petición choca con el estado actual, como un nombre de usuario ya ocupado o una edición sobre una versión desactualizada. 410 Gone: el recurso se eliminó para siempre. 415 Unsupported Media Type: el Content-Type del cuerpo no es aceptado. 422 Unprocessable Content: la petición es sintácticamente correcta pero los datos no son válidos. 429 Too Many Requests: se superó el límite de peticiones; suele venir con Retry-After.

La regla común a todos es que repetir la misma petición sin cambiarla volverá a fallar. Hay que corregir algo en el cliente: la URL, las credenciales o los datos.

5xx: errores del servidor

500 Internal Server Error: un fallo no controlado en la aplicación. 502 Bad Gateway: un proxy recibió una respuesta inválida de la aplicación, que a menudo se ha caído. 503 Service Unavailable: el servicio está sobrecargado o en mantenimiento, de forma temporal. 504 Gateway Timeout: la aplicación no respondió a tiempo al proxy.

Aquí la misma petición sí puede funcionar más tarde, por eso los clientes bien hechos reintentan los 502, 503 y 504 con espera exponencial. Solo deben hacerlo con operaciones idempotentes, como GET, PUT o DELETE, o con claves de idempotencia, para no crear dos pedidos por un reintento.

Elegir el código correcto en una API

El error de diseño más dañino es devolver 200 con un error en el cuerpo, como {"ok": false, "error": "no encontrado"}. Cachés, monitorización, reintentos automáticos y librerías cliente ven un éxito. Usa el código que corresponde y pon el detalle en el cuerpo, por ejemplo con el formato estándar application/problem+json de RFC 9457.

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.ejemplo.com/errores/pedido-no-encontrado",
  "title": "Pedido no encontrado",
  "status": 404,
  "detail": "No existe el pedido 1042 en esta cuenta."
}

Otras reglas útiles: 201 con Location al crear, 204 cuando no hay nada que devolver, 401 frente a 403 según si faltan credenciales o permisos, y nunca 500 para situaciones previstas como una validación fallida. Un conjunto pequeño de códigos usado con coherencia vale más que una tabla completa usada al azar.

Fuentes y lecturas recomendadas

RFC 9110 (HTTP Semantics), sección 15, define los códigos de estado y las clases. RFC 6585 añade 429, RFC 8297 define 103 Early Hints y RFC 9457 define el formato application/problem+json. El registro de la IANA «HTTP Status Code Registry» lista todos los códigos oficiales, y MDN tiene una referencia de cada código con ejemplos.

Frequently asked questions

¿Qué es un código de estado HTTP?

Un número de tres cifras que el servidor envía al principio de cada respuesta para indicar el resultado de la petición: éxito (2xx), redirección (3xx), error del cliente (4xx) o error del servidor (5xx).

¿Qué significa el código HTTP 201?

`201 Created`: la petición creó un recurso nuevo. Lo habitual es que la respuesta incluya la cabecera `Location` con la URL del recurso y, a menudo, su representación en el cuerpo.

¿Qué significa el código 400 en HTTP?

`400 Bad Request`: el servidor no pudo procesar la petición porque está mal formada, por ejemplo con JSON inválido o parámetros ilegibles. Hay que corregirla en el cliente antes de reintentar.

¿Cuál es la diferencia entre 4xx y 5xx?

4xx indica un error en la petición del cliente, que fallará igual si se repite sin cambios. 5xx indica un fallo del servidor, y la misma petición puede funcionar más tarde.

¿Cómo veo el código de estado de una página?

En el navegador, en la columna Status de la pestaña Red de las herramientas de desarrollo. En la terminal, con `curl -I URL` o `curl -s -o /dev/null -w '%{http_code}' URL`.

¿Está bien devolver 200 con un mensaje de error?

No. Cachés, monitorización y clientes interpretan 200 como éxito. Devuelve el código de error correspondiente y pon el detalle en el cuerpo, idealmente con `application/problem+json`.