Qué es un código de estado HTTP
Cada vez que un navegador, una aplicación o un script pide algo a un servidor web, la respuesta empieza con un número de tres cifras: el código de estado. Resume lo ocurrido: 200 significa que todo fue bien, 404 que el recurso no existe y 500 que el servidor falló. Los define el estándar HTTP (RFC 9110) y el registro de IANA, y sirven tanto a las personas que depuran un problema como a los programas, que deciden con ellos si reintentar, redirigir, mostrar un error o dar por buena la respuesta.
La primera cifra indica la familia, y es lo primero que conviene mirar. El texto que acompaña al número («Not Found») es solo una explicación para humanos: lo que cuenta es el código.
Cómo usar la referencia
- Escriba en el buscador un código (
429), el comienzo de uno (40muestra del 400 al 409) o una familia (5xx); también una palabra (redirección, caché, tiempo de espera) o el nombre de un servicio (Cloudflare, nginx). - Use los botones de familia para ver solo los errores del cliente (4xx), los del servidor (5xx), las redirecciones (3xx), etc.
- Pulse el número de un código para obtener un enlace directo a su fila (por ejemplo,
#c404), útil para compartirlo en un informe o una conversación. - Lea la columna «Cuándo se usa y cómo reaccionar»: explica el caso típico y qué hacer, tanto si usted consume una API como si la diseña.
Las cinco familias
| Familia | Significa | Quién tiene que actuar | Ejemplos |
|---|---|---|---|
| 1xx Informativos | La solicitud se recibió y el proceso continúa. | Normalmente nadie: los gestiona el navegador o la biblioteca HTTP. | 100, 101, 103 |
| 2xx Éxito | La solicitud se recibió, se entendió y se aceptó. | Nadie: todo fue bien. | 200, 201, 204 |
| 3xx Redirección | Hace falta otra acción, normalmente ir a otra dirección. | El cliente: seguir la redirección (Location) o usar la copia en caché. | 301, 302, 304, 308 |
| 4xx Error del cliente | La solicitud tiene un problema: es incorrecta, no autorizada o apunta a algo que no existe. | Quien envía la solicitud: corregirla. Repetirla igual da el mismo error. | 400, 401, 403, 404, 429 |
| 5xx Error del servidor | La solicitud era válida, pero el servidor no pudo atenderla. | Quien opera el servidor: investigar. El cliente puede reintentar más tarde. | 500, 502, 503, 504 |
Qué código devolver en una API
Elegir bien el código evita que quien consume su API tenga que adivinar. Estas son las decisiones que más se discuten:
| Situación | Código | Por qué |
|---|---|---|
| Se crea un recurso con POST | 201 Created, con Location | Distingue «creado» de «correcto» y dice dónde está. |
| Se acepta un trabajo que se hará después | 202 Accepted | El resultado aún no existe; indique cómo consultarlo. |
| Se borra o se actualiza sin devolver nada | 204 No Content | Éxito sin cuerpo: ahorra bytes y ambigüedades. |
| El JSON enviado está mal formado | 400 Bad Request | No se pudo ni leer. |
| El JSON es correcto, pero un campo no es válido | 422 Unprocessable Content | Error de validación semántica (correo sin «@», edad negativa). |
| No hay credenciales o son inválidas | 401 Unauthorized | Significa «no autenticado»: el cliente debe identificarse. |
| Está identificado, pero no tiene permiso | 403 Forbidden | Autenticarse otra vez no ayuda. |
| El recurso no existe (o no debe saberse que existe) | 404 Not Found | También para ocultar recursos privados a quien no debe verlos. |
| Se eliminó para siempre | 410 Gone | Más preciso que 404 para contenido retirado. |
| Duplicado, o edición sobre una versión vieja | 409 Conflict | El estado actual impide la operación. |
| Demasiadas peticiones | 429 Too Many Requests, con Retry-After | Limitación de tasa: dice cuánto esperar. |
| Fallo inesperado del servidor | 500 Internal Server Error | Sin detalles internos en la respuesta: regístrelos en el servidor. |
| Mantenimiento o sobrecarga | 503 Service Unavailable, con Retry-After | Temporal: los clientes y los buscadores vuelven a intentarlo. |
Códigos habituales por método HTTP
| Método | Éxito | Errores frecuentes |
|---|---|---|
| GET (leer) | 200 (con el recurso), 206 (parcial), 304 (sin cambios) | 400, 401, 403, 404, 410, 429 |
| POST (crear o ejecutar) | 201 (creado), 202 (aceptado), 200 o 204 | 400, 401, 403, 409, 415, 422, 429 |
| PUT (reemplazar) | 200 o 204; 201 si lo crea | 400, 404, 409, 412, 415, 422 |
| PATCH (modificar en parte) | 200 o 204 | 400, 404, 409, 412, 415, 422 |
| DELETE (borrar) | 204 (o 200 con un mensaje); 202 si se borra después | 401, 403, 404, 409 |
| HEAD y OPTIONS | 200 o 204 | 405 si no se permite |
Las redirecciones: 301, 302, 303, 307 y 308
Son las más confundidas. Se distinguen por dos preguntas: ¿el cambio es permanente? y ¿se conserva el método (POST, PUT…) y el cuerpo?
| Código | Permanente | Conserva el método | Úselo para |
|---|---|---|---|
| 301 Moved Permanently | Sí | No siempre (un POST puede pasar a GET) | Cambios de dominio o de dirección de páginas web. |
| 308 Permanent Redirect | Sí | Sí | Mover de forma permanente un endpoint de una API. |
| 302 Found | No | No siempre (un POST puede pasar a GET) | Redirecciones temporales de páginas, de uso general. |
| 307 Temporary Redirect | No | Sí | Redirección temporal de una API sin alterar el método. |
| 303 See Other | No | Siempre cambia a GET | Después de un POST: llevar al usuario a una página de resultado (Post/Redirect/Get). |
Para el posicionamiento en buscadores, una redirección permanente (301 o 308) indica que la nueva dirección sustituye a la antigua; una temporal (302 o 307) indica que la antigua sigue siendo la válida. Evite las cadenas largas de redirecciones: cada salto añade latencia, y los navegadores y rastreadores abandonan tras unos pocos.
Encabezados que acompañan a cada código
| Código | Encabezado | Para qué |
|---|---|---|
| 201, 301, 302, 303, 307, 308 | Location | La dirección del recurso creado o a la que se redirige. |
| 401 | WWW-Authenticate | Cómo debe autenticarse el cliente (Bearer, Basic…). |
| 405 | Allow | Los métodos que sí admite el recurso. |
| 429, 503 | Retry-After | Cuántos segundos esperar, o a partir de qué fecha reintentar. |
| 206 | Content-Range | Qué parte del recurso contiene la respuesta. |
| 304 | ETag, Cache-Control | Los validadores de la caché que justifican la respuesta sin cuerpo. |
| 4xx, 5xx | Content-Type: application/problem+json | Un formato estándar (RFC 9457) para describir errores en las API. |
Distinguir los errores 500, 502, 503 y 504
| Código | Qué indica | Dónde mirar |
|---|---|---|
| 500 | La aplicación falló al procesar la solicitud. | Los registros de la aplicación: excepciones, configuración, base de datos. |
| 502 | El proxy o balanceador recibió una respuesta inválida (o ninguna) de la aplicación. | Que la aplicación esté en marcha y escuche en el puerto correcto; fallos al arrancar. |
| 503 | El servicio no puede atender ahora: sobrecarga o mantenimiento. | Capacidad, límites de conexiones, modo de mantenimiento. |
| 504 | El proxy esperó demasiado la respuesta de la aplicación. | Consultas lentas, procesos largos y los tiempos de espera del proxy (proxy_read_timeout en nginx). |
Con Cloudflare, los errores 520 a 526 son más específicos: indican dónde falló la conexión entre Cloudflare y su servidor de origen (conexión rechazada, tiempo agotado, certificado inválido, etc.). Están en la tabla, con la causa más probable de cada uno.
Buenas prácticas
- No devuelva 200 con un error en el cuerpo. Los clientes, las cachés y las herramientas de monitoreo se fían del código: si todo es 200, nadie se entera de que algo falló.
- Incluya un mensaje útil en los errores 4xx (qué campo falló y por qué), sin revelar detalles internos como rutas o trazas.
- Use 401 y 403 con precisión: el primero pide identificarse; el segundo, que quien está identificado no tiene permiso.
- Reintente solo lo que se puede reintentar: los 429, 503 y 504 (con espera, respetando
Retry-After) y las operaciones idempotentes. Un 4xx no se arregla reintentando. - Cuide las páginas de error. Una página 404 con enlaces útiles y un código 404 real (no un 200 «blando») es mejor para las personas y para los buscadores.
Si trabaja con tokens en las cabeceras de autenticación, vea el decodificador JWT; para los datos que viajan en el cuerpo de las respuestas, el validador JSON.
Preguntas frecuentes
¿Cuál es la diferencia entre 401 y 403?
El 401 significa «no autenticado»: faltan credenciales válidas, y el cliente puede volver a intentarlo identificándose. El 403 significa «prohibido»: el servidor sabe quién es el usuario, pero no tiene permiso, de modo que identificarse de nuevo no cambia nada.
¿Cuándo uso 301 y cuándo 302?
Use 301 (o 308) cuando el cambio de dirección es permanente: los buscadores transfieren el posicionamiento a la nueva URL. Use 302 (o 307) cuando es temporal y la dirección original seguirá siendo la válida. Si redirige solicitudes POST y quiere conservar el método, elija 307 o 308.
¿Qué significa un error 502 Bad Gateway?
Que un servidor intermedio (proxy, balanceador o CDN) pidió la respuesta a la aplicación y recibió algo inválido o nada. Casi siempre la aplicación está caída, se reinició o no escucha donde el proxy espera.
¿Qué diferencia hay entre 400 y 422?
El 400 indica que la solicitud no se pudo interpretar (JSON mal formado, parámetros ilegibles). El 422 indica que se entendió perfectamente, pero su contenido no pasa la validación (un correo sin formato válido, un valor fuera de rango).
¿Qué es un error 429?
Too Many Requests: el cliente superó el límite de peticiones permitido. La respuesta debería incluir Retry-After con el tiempo de espera, y el cliente debe respetarlo antes de reintentar.
¿Qué significa 418 «Soy una tetera»?
Es una broma del RFC 2324 (el protocolo de control de cafeteras, publicado un 1 de abril): una tetera se niega a preparar café. No tiene uso real, aunque algunos servicios lo devuelven como huevo de Pascua o para rechazar bots.
¿Son oficiales los códigos de Cloudflare como 522 o 524?
No: están fuera del estándar. Los define Cloudflare para explicar qué falló entre su red y su servidor de origen. Lo mismo ocurre con el 499 y el 444 de nginx o el 419 de Laravel; la tabla los marca como «No estándar».