Códigos de Estado HTTP

Definición

Los códigos de estado HTTP son números de tres dígitos que te dicen el resultado de una petición HTTP. Cada respuesta HTTP incluye un código de estado: es la forma del servidor de decir “esto es lo que pasó con tu petición.”

Los códigos de estado están agrupados en cinco clases por su primer dígito: 1xx (informacional), 2xx (éxito), 3xx (redirección), 4xx (error de cliente), y 5xx (error de servidor). El más famoso es probablemente 404 Not Found, pero hay docenas más, cada uno con significado específico.

Entender los códigos de estado es crucial para construir y depurar APIs. Dejan saber a los clientes si necesitan reintentar (5xx), si cometieron un error (4xx), si deben redirigir (3xx), o si todo funcionó perfectamente (2xx).

Ejemplo

2xx Éxito: 200 OK (GET exitoso), 201 Created (POST exitoso), 204 No Content (DELETE exitoso)

4xx Errores de Cliente: 400 Bad Request (JSON inválido), 401 Unauthorized (falta autenticación), 403 Forbidden (falta permiso), 404 Not Found (recurso no existe), [429 Too Many Requests](https://reference.apios.info/es/terms/429-too-many-requests/) (limitación de tasa)

5xx Errores de Servidor: 500 Internal Server Error (servidor falló), 502 Bad Gateway (servidor upstream falló), 503 Service Unavailable (servidor sobrecargado)

3xx Redirecciones: 301 Moved Permanently (recurso reubicado), 304 Not Modified (versión cacheada está actualizada)

Diagrama

graph TD
A[Códigos de Estado HTTP] --> B[1xx Informacional]
A --> C[2xx Éxito]
A --> D[3xx Redirección]
A --> E[4xx Error de Cliente]
A --> F[5xx Error de Servidor]
C --> C1[200 OK]
C --> C2[201 Created]
C --> C3[204 No Content]
E --> E1[400 Bad Request]
E --> E2[401 Unauthorized]
E --> E3[403 Forbidden]
E --> E4[404 Not Found]
E --> E5[429 Too Many Requests]
F --> F1[500 Internal Server Error]
F --> F2[502 Bad Gateway]
F --> F3[503 Service Unavailable]

Mejores Prácticas

1. Usar el código de estado más específico disponible
2. Devolver 2xx para operaciones exitosas
3. Usar 4xx para errores del cliente (entrada incorrecta, falta autenticación)
4. Usar 5xx solo para fallos reales del servidor
5. Devolver 201 Created (no 200 OK) para creación POST
6. Devolver 204 No Content para éxito DELETE
7. Incluir detalles de error en el cuerpo de respuesta para 4xx/5xx
8. Usar 429 con cabecera Retry-After para limitación de tasa
9. Evitar devolver 200 para operaciones fallidas
10. Documentar qué códigos de estado devuelve cada endpoint

Errores Comunes

Devolver 200 OK para todo (incluso errores), usar 500 cuando es un error de cliente (usar 400), devolver 404 cuando el recurso existe pero el usuario no tiene permiso (usar 403), no incluir detalles de error en el cuerpo de respuesta, formato de error inconsistente entre endpoints, devolver 201 sin cabecera Location.

Estándares & RFCs

Términos Relacionados