Guía Completa de Códigos de Estado HTTP | Causas de Errores Comunes y Soluciones
Al desarrollar una API, obtiene una respuesta 422. En producción, de repente aparece un 502. Si un redireccionamiento es 301 o 302 cambia el impacto en SEO. Los códigos de estado HTTP son el idioma común del desarrollo web, y comprenderlos correctamente es el primer paso para solucionar problemas.
Cinco categorías de códigos de estado
| Rango | Categoría | Significado |
|---|---|---|
| 1xx | Informational | Solicitud recibida y procesando |
| 2xx | Success | Solicitud exitosa |
| 3xx | Redirection | Acción adicional requerida (redirección) |
| 4xx | Client Error | Problemas del lado del cliente |
| 5xx | Server Error | Problema del lado del servidor |
Código que los desarrolladores encuentran con más frecuencia
200 OK — Éxito
La respuesta de éxito más básica. La API está funcionando como se esperaba.
301 Moved Permanently — Redirección permanente
Se utiliza cuando una URL cambia permanentemente. <strong>Para SEO, la autoridad de la URL antigua se transfiere a la nueva URL</strong>, siendo esencial para migraciones de sitios e implementación de HTTPS. Google trata 301 como "transferencia de señal".
<strong>Problema común</strong>: Devolver 302 cuando se pretendía 301. El <code>Redirect</code> de Apache tiene 302 por defecto. Especifique explícitamente <code>Redirect 301</code>.
302 Found — Redirección temporal
Redirección temporal. Se utiliza para pruebas A/B y desvíos de mantenimiento. El valor de SEO no se transfiere.
304 Not Modified — Caché válido
Se devuelve cuando el navegador envía una solicitud condicional con headers <code>If-Modified-Since</code> o <code>If-None-Match</code> y el recurso no ha cambiado. <strong>No se envía cuerpo</strong>, por lo que se puede ahorrar ancho de banda.
400 Bad Request — Solicitud inválida
El servidor no puede analizar la solicitud. Causa: JSON inválido, parámetros requeridos faltantes o desajuste de Content-Type.
# よくあるミス: Content-Type を指定していない
curl -X POST https://api.example.com/users -d '{"name":"Alice"}'
# → 400 (Content-Type: application/json が必要)
# 正しい
curl -X POST https://api.example.com/users \
-H 'Content-Type: application/json' \
-d '{"name":"Alice"}'401 Unauthorized — Se requiere autenticación
Credenciales de autenticación faltantes o inválidas. El token Bearer ha expirado o la clave API es incorrecta.
403 Forbidden — Acceso denegado
La autenticación fue exitosa, pero no hay autorización. Por ejemplo, cuando un usuario regular accede a un punto de conexión solo para administradores. La diferencia con 401 es "presencia/ausencia de autenticación" vs "presencia/ausencia de autorización".
404 Not Found — Recurso no encontrado
El error más famoso. Causado por errores tipográficos en URL, páginas eliminadas o errores de configuración de enrutamiento. Para fines de SEO, a veces es preferible usar <code>410 Gone</code> para indicar 「eliminado intencionalmente」.
413 Payload Too Large — Tamaño excedido
Frecuente en cargas de archivos. Verifique <code>client_max_body_size</code> de Nginx (predeterminado 1MB), <code>upload_max_filesize</code> de PHP y los límites de API Gateway.
422 Unprocessable Entity — Error de validación
La sintaxis JSON es correcta pero inválida desde una perspectiva de lógica empresarial (formato de correo electrónico inválido, campo requerido vacío, etc.). Las API REST generalmente devuelven esto para errores de validación.
429 Too Many Requests — Limitación de velocidad
Demasiadas solicitudes enviadas en poco tiempo. El encabezado <code>Retry-After</code> indica cuántos segundos esperar. Contramedida: Implementar exponential backoff.
500 Internal Server Error — Error interno del servidor
Excepciones no controladas, referencias NULL, errores de archivo de configuración. <strong>Error más peligroso</strong>. Siempre verifique los registros del servidor.
502 Bad Gateway — Anomalía del servidor ascendente
El proxy inverso (Nginx) no pudo conectarse a PHP-FPM / Node.js / Python WSGI ascendente o recibió una respuesta inválida. Verifique el reinicio del proceso ascendente, memoria insuficiente o tiempos de espera de conexión de socket.
503 Service Unavailable — Servicio temporalmente no disponible
Mantenimiento o sobrecarga del servidor. Incluya un encabezado <code>Retry-After</code> para informar al cliente que espere.
504 Gateway Timeout — Tiempo de espera agotado en el servidor ascendente
El servidor ascendente no respondió a tiempo. Consultas de BD pesadas, retrasos de API externos. Verifique <code>proxy_read_timeout</code> de Nginx.
Herramienta de búsqueda de códigos de estado de DevLab
<a href="/ja/tools/http-status/">Herramienta de Búsqueda de Códigos de Estado HTTP</a> te permite buscar instantáneamente por número de código o palabra clave (p. ej., "redirect", "forbidden", "timeout"), y ver el significado, causa y solución para cada código en una lista única. Funciona completamente en tu navegador sin necesidad de registro.
Herramientas relacionadas: <a href="/ja/check/headers/">validación de encabezados HTTP</a>, <a href="/ja/check/redirect-chain/">seguimiento de cadena de redirección</a>, <a href="/ja/check/security/">diagnóstico de seguridad</a>.
Resumen
Los códigos de estado HTTP son el lenguaje común entre servidor y cliente. El conocimiento clave incluye el impacto SEO de 301 vs 302, la distinción de validación entre 400 vs 422 y el diagnóstico de infraestructura para códigos 5xx. Cuando tengas dudas, primero verifica el código de estado y aplica los remedios anteriores.