Códigos de estado HTTP
Busca y entiende los códigos de respuesta HTTP, sus categorías y recomendaciones prácticas.
Códigos frecuentes
58 códigos de estado
¿Qué es un código de estado HTTP?
Un código de estado HTTP es el número de tres dígitos que el servidor devuelve con cada respuesta e indica al cliente si la petición se resolvió, se redirigió o falló. El primer dígito agrupa el significado: 1xx informativo, 2xx éxito, 3xx redirección, 4xx error del cliente, 5xx error del servidor.
Esta referencia lista cada código registrado con su nombre oficial y la situación para la que está pensado, para que elijas el correcto al construir una API en lugar de recurrir siempre a 200 o 500.
Cómo consultar un código de estado
- Escribe el número (429) o una palabra del nombre (timeout, gateway) en el cuadro de búsqueda.
- Acota la lista con los filtros 1xx–5xx si ya sabes la clase de error.
- Haz clic en una fila para abrir su panel de detalle, que explica cuándo debe devolverlo un servidor.
- Copia el código con el botón de copiar, o abre la página de MDN para ver la especificación completa.
- Compara códigos vecinos antes de decidir: 401 frente a 403 y 301 frente a 307 son las parejas que más se confunden.
Ejemplos de códigos de estado
Autenticación frente a permiso
GET /admin — sin token
401 Unauthorized: el cliente debe autenticarse primero
Límite de peticiones
100 peticiones en un segundo
429 Too Many Requests: añade Retry-After y baja el ritmo
Parejas de códigos que se confunden
| Criterio | 401 Unauthorized | 403 Forbidden |
|---|---|---|
| Significado | Faltan credenciales o no son válidas | Está autenticado pero no tiene permiso |
| Reintentar tras iniciar sesión | Sí, normalmente funciona | No, hay que cambiar los permisos |
| Causa habitual | Token caducado | Al rol le falta un permiso |
| Cabecera WWW-Authenticate | Se espera | No es obligatoria |
Preguntas frecuentes sobre códigos de estado
¿Cuál es la diferencia entre 401 y 403?
401 significa que la petición no lleva credenciales válidas; 403 significa que quien llama está autenticado pero no tiene permiso para esa acción.
¿Cuándo devuelvo 404 en lugar de 403?
Devuelve 404 cuando revelar que el recurso existe filtraría información, por ejemplo el registro privado de otro cliente.
¿301 o 308 para una redirección permanente?
301 permite que el método cambie a GET en algunos clientes; 308 conserva el método y el cuerpo. Usa 308 en endpoints que no sean GET.
¿Un 200 OK vale para una búsqueda fallida?
No. Usa 404 Not Found para que clientes y rastreadores reaccionen bien.
¿Qué código devuelve un error de validación?
422 Unprocessable Content cuando la sintaxis es válida pero la semántica falla; 400 Bad Request cuando la petición está mal formada.
¿Puedo usar 500 para fallos previstos?
No. Los 5xx señalan un fallo del servidor que requiere atención. Para problemas causados por el cliente usa 4xx.