Los códigos de estado HTTP son el lenguaje que usan los servidores para responder a las solicitudes. Entender lo que significa cada código es fundamental para cualquier desarrollador, DevOps o diseñador que trabaje con APIs o aplicaciones web.
Cómo Se Organizan los Códigos
Todos los códigos HTTP tienen 3 dígitos. El primer dígito define la categoría:
| Rango | Categoría | Significado | |---|---|---| | 1xx | Informativo | La solicitud fue recibida y está siendo procesada | | 2xx | Éxito | La solicitud fue recibida, entendida y aceptada | | 3xx | Redirección | Se necesitan más acciones para completar la solicitud | | 4xx | Error del cliente | La solicitud contiene sintaxis incorrecta o no puede atenderse | | 5xx | Error del servidor | El servidor falló al atender una solicitud aparentemente válida |
Códigos 1xx: Informativos
100 Continue
El servidor recibió los encabezados de la solicitud y el cliente puede continuar enviando el cuerpo.
101 Switching Protocols
El servidor acepta cambiar de protocolo según lo solicitado por el cliente (ej.: HTTP a WebSocket).
102 Processing
El servidor está procesando la solicitud pero aún no tiene respuesta disponible (WebDAV).
103 Early Hints
Permite que el cliente empiece a precargar recursos mientras el servidor prepara la respuesta completa.
Códigos 2xx: Éxito
200 OK
La solicitud fue exitosa. El significado depende del método HTTP utilizado.
201 Created
La solicitud fue exitosa y se creó un nuevo recurso. Se usa en respuesta a solicitudes POST y PUT.
202 Accepted
La solicitud fue aceptada pero aún no se ha procesado. Común en procesamientos asíncronos.
204 No Content
La solicitud fue exitosa pero no hay contenido que devolver. Común en DELETE y PUT.
206 Partial Content
El servidor está entregando solo parte del recurso (usado en descargas con rango o streaming de video).
Códigos 3xx: Redirección
301 Moved Permanently
El recurso se movió permanentemente a una nueva URL. Los buscadores transfieren la autoridad del enlace a la nueva dirección.
302 Found
Redirección temporal. El cliente debe usar la URL original en las próximas solicitudes.
304 Not Modified
Indica que el recurso no ha cambiado desde la última solicitud. El cliente puede usar su versión en caché.
307 Temporary Redirect
Igual que el 302, pero garantiza que el método HTTP original no se cambiará.
308 Permanent Redirect
Igual que el 301, pero garantiza que el método HTTP original no se cambiará.
Códigos 4xx: Error del Cliente
400 Bad Request
La solicitud está mal formada, es inválida o no puede procesarse. Revisa el formato de los datos enviados.
401 Unauthorized
Se requiere autenticación. En la práctica significa "no autenticado": el cliente no proporcionó credenciales válidas.
403 Forbidden
El servidor entendió la solicitud pero se niega a atenderla. El cliente está autenticado pero no tiene permiso.
404 Not Found
El recurso solicitado no se encontró. Puede ser temporal o permanente.
405 Method Not Allowed
El método HTTP usado (ej.: DELETE) no está soportado para ese endpoint.
408 Request Timeout
El servidor cerró la conexión por inactividad del cliente.
409 Conflict
La solicitud entra en conflicto con el estado actual del recurso (ej.: intento de crear un duplicado).
410 Gone
El recurso existió pero fue eliminado de forma permanente. A diferencia del 404, indica una eliminación intencional.
413 Content Too Large
El cuerpo de la solicitud supera el límite configurado en el servidor.
422 Unprocessable Content
La solicitud está bien formada pero contiene errores semánticos (muy usado en APIs REST para validación de datos).
429 Too Many Requests
El cliente envió demasiadas solicitudes en poco tiempo (limitación de velocidad).
Códigos 5xx: Error del Servidor
500 Internal Server Error
Error genérico del servidor. Algo salió mal sin encajar en ningún otro código 5xx.
501 Not Implemented
El servidor no soporta la funcionalidad necesaria para atender la solicitud.
502 Bad Gateway
El servidor, actuando como gateway, recibió una respuesta inválida del upstream.
503 Service Unavailable
El servidor está temporalmente no disponible por sobrecarga o mantenimiento.
504 Gateway Timeout
El servidor, actuando como gateway, no recibió respuesta del upstream a tiempo.
507 Insufficient Storage
El servidor no tiene espacio suficiente para completar la solicitud (WebDAV).
Consejos Prácticos
Usa 201 en lugar de 200 al crear recursos: devolver 201 Created con el encabezado Location apuntando al nuevo recurso es la forma semánticamente correcta de responder a un POST exitoso.
401 vs 403: 401 significa "necesitas autenticarte", 403 significa "estás autenticado pero no tienes permiso". Confundirlos es un error clásico.
Usa siempre 422 para errores de validación: muchas APIs todavía usan 400 para todo, pero 422 es semánticamente más correcto cuando el problema está en los datos enviados, no en el formato de la solicitud.
Caché y 304: implementar soporte para ETag e If-None-Match permite que los clientes usen la caché correctamente, reduciendo ancho de banda y latencia.
Preguntas Frecuentes
¿Cuál es la diferencia entre 404 y 410? 404 significa "no encontrado ahora"; puede ser temporal. 410 significa "eliminado intencionalmente y no vuelve". Los buscadores los tratan diferente: eliminan el 410 del índice más rápidamente.
¿Por qué mi API devuelve 200 incluso cuando hay un error? Patrón llamado "200 OK with error body": muy común en APIs antiguas. Se considera mala práctica porque rompe el contrato del protocolo HTTP y dificulta el uso de herramientas de monitoreo.
¿Existe el código 418?
Sí, 418 I'm a teapot es real. Fue definido en el RFC 2324 como una broma del Día de los Inocentes de 1998. Algunos servidores lo implementan como easter egg.
¿Trabajando con APIs? El Formateador JSON de UtilWave te ayuda a visualizar y validar los cuerpos de solicitud y respuesta con un solo clic.