Códigos de estado HTTP
Todos los códigos de estado HTTP registrados: qué significan, cuándo aparecen y dónde están definidos.
Select a code
¿Qué son los códigos de estado HTTP?
Toda respuesta HTTP empieza con un código de estado de tres dígitos que dice qué le pasó a la petición. El primer dígito indica la clase: 1xx es informativo, 2xx significa éxito, 3xx significa redirección, 4xx significa que la petición estaba mal y 5xx que el servidor falló.
Los códigos están definidos en la RFC 9110, HTTP Semantics, que sustituyó a la RFC 7231 en 2022, y en algunas otras RFC, como la RFC 6585 para 429 Too Many Requests. La IANA mantiene el registro oficial. La RFC 9110 renombró dos códigos: 413 ahora es Content Too Large (antes Payload Too Large) y 422 es Unprocessable Content (antes Unprocessable Entity). Los números y su comportamiento no cambiaron.
Algunos códigos que te vas a encontrar no están en el registro. nginx registra 499 cuando un cliente cierra la conexión antes de que la respuesta esté lista, Cloudflare envía del 520 al 526 cuando no consigue una respuesta válida del servidor de origen, y Laravel envía 419 cuando el token CSRF de un formulario ha caducado. Aparecen aparte, marcados como no oficiales.
El código de estado es lo primero que debe comprobar una prueba de API, porque el resto de la respuesta depende de él. Un 201 Created te dice que un POST creó un recurso nuevo, un 404 que el recurso no existe y un 500 que el servidor falló, en cuyo caso el cuerpo puede ser una página de error en lugar del JSON que esperabas.
Cómo usar esta herramienta
- 1Recorre la lista, agrupada del 1xx al 5xx con los códigos no oficiales al final, o fíltrala con los botones de clase.
- 2Busca por número, nombre o síntoma, como
404,5xx,redirect,timeouto un nombre antiguo comoUnprocessable Entity. Pulsa / para ir al buscador desde cualquier punto de la página. - 3Selecciona un código, o recorre la lista con las flechas del teclado, para ver qué significa, cuándo aparece, la especificación que lo define y códigos relacionados con los que compararlo.
- 4Copia el comando
curlde Try it para que el endpoint de estado de testingapis.com devuelva ese código, o copia un enlace:/es/tools/http-status/#429abre directamente el 429.
Solución de problemas
- Un 401 aunque enviaste un token
- El token está caducado, mal formado, va en la cabecera equivocada o le falta el prefijo
Bearer. La cabecera de respuestaWWW-Authenticatesuele indicar cuál. Un 403, en cambio, significa que el token es válido pero no tiene permiso. - Un 415 con un cuerpo JSON
- La petición no lleva la cabecera
Content-Type: application/json, así que el servidor no trata el cuerpo como JSON. El-dde curl envíaapplication/x-www-form-urlencodedsalvo que fijes la cabecera. - Un POST se convierte en GET después de una redirección
- Los clientes siguen los 301 y 302 repitiendo la petición como GET y sin cuerpo. Los servidores que necesitan conservar el método deben enviar 307 o 308.
- Un 502 o un 504 de un balanceador de carga
- El proxy que está delante de la aplicación no recibió una respuesta válida: 502 cuando la aplicación se cayó o cerró la conexión, 504 cuando tardó más que el timeout del proxy. Los logs de la propia aplicación muestran la causa.
- 499 en los logs de nginx
- El cliente se rindió antes de que la respuesta estuviera lista: un usuario se fue de la página, o un cliente o un proxy intermedio agotó su timeout. Lo habitual es que la causa sean peticiones lentas al backend.
Preguntas frecuentes
¿Qué diferencia hay entre 401 y 403?
401 Unauthorized significa que el servidor no sabe quién eres: faltan las credenciales, han caducado o son incorrectas. 403 Forbidden significa que sabe quién eres, pero esa identidad no tiene permiso para hacer eso. Volver a iniciar sesión puede arreglar un 401, no un 403.
¿Una API debe devolver 400 o 422 ante una entrada no válida?
Se usan los dos. Una convención habitual es 400 para una petición que el servidor no puede ni leer, como un JSON mal formado, y 422 para datos bien formados que incumplen una regla, como un campo obligatorio que falta o un email no válido.
¿Qué diferencia hay entre 502, 503 y 504?
Los tres suelen venir de un proxy o un balanceador de carga situado delante de la aplicación. 502 Bad Gateway significa que recibió una respuesta no válida del servidor que tiene detrás, 503 Service Unavailable que el servicio está sobrecargado o en mantenimiento, y 504 Gateway Timeout que el servidor de detrás no respondió a tiempo.
¿Qué código de redirección debo usar?
301 y 308 son permanentes; 302 y 307, temporales. 307 y 308 obligan al cliente a repetir la petición con el mismo método y el mismo cuerpo, mientras que los clientes suelen convertir un POST en GET tras un 301 o un 302. Usa 303 See Other para mandar al cliente a una página de resultados después de un POST.
¿418 I'm a teapot es un código de estado real?
Viene de la RFC 2324, una broma del Día de los Inocentes anglosajón (1 de abril) de 1998 sobre cómo controlar cafeteras. La RFC 9110 lista el 418 como no usado pero reservado, porque muchísimo software ya lo reconoce. No está pensado para errores reales.
¿Cómo pruebo cómo maneja mi app un código de estado concreto?
Llama a un endpoint que devuelva el código que pidas. GET https://api.testingapis.com/api/status/503 responde con un 503 y las cabeceras que suele llevar ese estado, como Retry-After. Funciona cualquier código del 200 al 599.