Consulta de Codigos de Estado HTTP

El HTTP Status Code Lookup proporciona acceso instantáneo a explicaciones detalladas para cada código de estado de respuesta HTTP del 100 al 599, incluyendo referencias RFC, casos de uso comunes y las distinciones sutiles entre códigos frecuentemente confundidos. Ingresa un código como 403 o busca por palabra clave como "redirect" para obtener el nombre oficial, significado y orientación práctica sobre cuándo usarlo en tus propias APIs.

Entendiendo los códigos de estado HTTP

Cada respuesta HTTP comienza con un código de estado de tres dígitos que le dice al cliente qué sucedió con su solicitud. Si alguna vez has visto una página 404, recibido un error 500 de una API, o sido redirigido silenciosamente por un 301, has encontrado códigos de estado en acción. Son lo primero que tu navegador, cliente HTTP o sistema de monitoreo verifica cuando llega una respuesta, y elegir el código correcto en tus propias APIs es esencial para construir sistemas que se comporten de manera predecible y sean fáciles de depurar.

Los códigos de estado se agrupan en cinco clases por su primer dígito. Los códigos 1xx son informativos -- el servidor está reconociendo la solicitud pero no ha terminado de procesarla. Los códigos 2xx indican éxito -- la solicitud fue recibida, entendida y procesada correctamente. Los códigos 3xx manejan redirecciones -- el cliente necesita tomar una acción adicional, generalmente seguir una nueva URL. Los códigos 4xx señalan errores del cliente -- la solicitud estaba malformada, no autorizada, o apuntaba a algo que no existe. Y los códigos 5xx indican errores del servidor -- el servidor entendió la solicitud pero falló al procesarla debido a un problema interno.

El desafío no es saber que 200 significa éxito o 404 significa no encontrado -- esos son bien conocidos. La complejidad real está en las distinciones sutiles. ¿Deberías usar 401 o 403 cuando un usuario carece de permiso? ¿Es 301 o 308 la redirección correcta para un endpoint POST que se ha movido? ¿Debería una búsqueda sin resultados devolver 200 con un cuerpo vacío, 204 o 404? Esta herramienta explica estas distinciones con orientación práctica para que puedas tomar la decisión correcta para tu caso de uso específico.

Cómo buscar un código de estado HTTP

1. Ingresa un número de código de estado (por ejemplo, 404) o busca por palabra clave (por ejemplo, "redirect", "unauthorized").
2. Ve el nombre oficial, la referencia RFC y la explicación detallada.
3. Lee la orientación de caso de uso sobre cuándo devolver ese código en tu propia API.

Referencia rápida de códigos de estado HTTP

Informativos (1xx)

Éxito (2xx)

Redirección (3xx)

Error del cliente (4xx)

Error del servidor (5xx)

Códigos de estado frecuentemente confundidos

301 vs. 302 vs. 307 vs. 308

• 301 Moved Permanently -- Úsalo cuando la URL de un recurso ha cambiado para siempre. Los navegadores y motores de búsqueda pueden cambiar POST a GET en la redirección.
• 302 Found -- Redirección temporal. Históricamente, los navegadores cambiaban POST a GET a pesar de que la especificación decía que no deberían. Ambiguo en la práctica.
• 307 Temporary Redirect -- Como 302, pero el navegador debe preservar el método HTTP original (POST sigue siendo POST).
• 308 Permanent Redirect -- Como 301, pero el navegador debe preservar el método HTTP original. Usa este en lugar de 301 al redirigir envíos de formularios.

401 vs. 403

• 401 Unauthorized -- El cliente no ha proporcionado credenciales de autenticación válidas. La respuesta debe incluir un header WWW-Authenticate indicando el esquema de autenticación esperado.
• 403 Forbidden -- El cliente está autenticado (o no se requiere autenticación), pero no tiene permiso para acceder al recurso. Re-autenticarse no ayudará.

404 vs. 410

• 404 Not Found -- El recurso no está disponible. Puede que nunca haya existido, o puede existir en el futuro.
• 410 Gone -- El recurso existió previamente pero ha sido eliminado intencional y permanentemente. Los motores de búsqueda desindexarán la URL más rápido con 410 que con 404.

500 vs. 502 vs. 503 vs. 504

• 500 -- El servidor mismo encontró un error al procesar la solicitud (excepción no manejada, bug).
• 502 -- Un proxy inverso o balanceador de carga recibió una respuesta inválida de un servidor upstream.
• 503 -- El servidor temporalmente no puede manejar solicitudes (sobrecargado, en mantenimiento). A menudo incluye un header Retry-After.
• 504 -- Un proxy inverso o balanceador de carga agotó el tiempo de espera del servidor upstream.

Cuándo usar esta herramienta

• Diseñando APIs RESTful -- Elige códigos de estado semánticamente correctos para cada endpoint y condición de error.
• Depurando respuestas de API -- Entiende qué significa un código de estado desconocido o inesperado en los logs del servidor.
• Manejando redirecciones -- Determina si usar 301, 302, 307 o 308 para tu escenario de redirección específico.
• Configurando alertas de monitoreo -- Configura alertas para códigos de estado específicos con entendimiento de lo que indica cada uno.
• Optimización SEO -- Usa los códigos de redirección correctos (301 vs 302) para preservar las clasificaciones en motores de búsqueda durante migraciones de URL.
• Triaje de incidentes -- Identifica rápidamente si un error 5xx proviene de tu aplicación (500) o de la infraestructura (502, 504).

Orientación práctica para códigos de estado de API

Uno de los errores más comunes en el diseño de API es usar en exceso 200 OK para todo, incluyendo errores. Algunas APIs devuelven 200 con un mensaje de error en el cuerpo, obligando al cliente a analizar la respuesta para determinar si la solicitud realmente tuvo éxito. Esto rompe las herramientas HTTP estándar, hace que el monitoreo sea poco confiable y confunde a los desarrolladores que esperan que los códigos de estado HTTP reflejen el resultado real. Usa 200 para éxito, 4xx para errores del cliente y 5xx para errores del servidor -- para eso están los códigos.

Otra fuente frecuente de confusión es la elección entre 404 y respuestas de éxito vacías. Si un usuario busca productos y la búsqueda devuelve cero resultados, la respuesta correcta es 200 con un array vacío -- el endpoint de búsqueda existe, funcionó y no encontró nada. Si el usuario solicita un producto específico por ID y ese producto no existe, la respuesta correcta es 404 -- el recurso que pidieron no está ahí. La distinción es entre "hice lo que pediste y la respuesta es nada" (200) versus "lo que preguntaste no existe" (404).

Para APIs que sirven tanto a usuarios autenticados como no autenticados, ten cuidado con la información que filtras a través de los códigos de estado. Responder con 403 a una solicitud no autorizada para /admin/users confirma que el endpoint existe. Responder con 404 en su lugar no revela nada sobre la estructura de tus URLs. La comunidad de seguridad llama a esto "seguridad por oscuridad" y tiene límites, pero es una medida razonable de defensa en profundidad para endpoints sensibles.

Preguntas frecuentes

¿Cuáles son los códigos de estado 5xx personalizados de CloudFlare?

CloudFlare usa códigos del 520 al 527 para problemas entre sus servidores edge y los servidores de origen. Por ejemplo, 520 significa que el origen devolvió una respuesta inesperada, 521 significa que el servidor web de origen está caído, 522 significa que la conexión al origen agotó el tiempo, y 524 significa que el origen respondió pero tardó demasiado.

¿Hay diferencia entre "Unauthorized" y "Unauthenticated"?

Técnicamente, HTTP 401 debería llamarse "Unauthenticated" porque significa que el cliente no ha probado su identidad. El nombre "Unauthorized" es un error histórico en la especificación. El verdadero fallo de autorización (estás autenticado pero careces de permiso) es 403 Forbidden.

¿Debería usar 404 o 204 cuando una búsqueda no devuelve resultados?

Usa 200 con un conjunto de resultados vacío. El recurso (el endpoint de búsqueda) existe y respondió exitosamente -- simplemente no encontró elementos coincidentes. Reserva 404 para cuando el endpoint mismo no existe.

¿Cuándo debería usar 429 Too Many Requests?

Usa 429 cuando un cliente ha excedido el límite de tasa de tu API. Incluye un header Retry-After indicando cuántos segundos debe esperar el cliente antes de reintentar. También incluye headers X-RateLimit-Limit y X-RateLimit-Remaining para que los clientes puedan ver el estado actual de su cuota sin alcanzar el límite.

¿Cuál es la diferencia entre 502 y 504 en una configuración de proxy inverso?

Un 502 Bad Gateway significa que el proxy recibió una respuesta del servidor upstream, pero la respuesta era inválida o malformada (por ejemplo, el upstream devolvió datos basura o cerró la conexión a mitad de respuesta). Un 504 Gateway Timeout significa que el proxy nunca recibió una respuesta en absoluto -- el servidor upstream no respondió dentro del período de timeout configurado. Ambos indican problemas upstream, pero 504 típicamente sugiere que el upstream está sobrecargado o inaccesible, mientras que 502 sugiere que está respondiendo pero comportándose incorrectamente.

¿Debería devolver 201 Created o 200 OK después de crear un recurso?

Usa 201 Created para solicitudes POST que crean un nuevo recurso. Incluye un header Location apuntando a la URL del recurso recién creado. Esto sigue las convenciones REST y ayuda a los clientes a localizar el nuevo recurso sin analizar el cuerpo de la respuesta. Usa 200 para actualizaciones de recursos existentes (PUT/PATCH).

Herramientas relacionadas

• HTTP Header Formatter - Analiza y formatea headers de respuesta HTTP que acompañan códigos de estado
• CORS Header Explainer - Entiende errores CORS que producen códigos de estado específicos
• MIME Type Lookup - Busca headers Content-Type devueltos con respuestas HTTP
• Cookie Header Parser - Analiza headers Set-Cookie de respuestas HTTP
• curl Command Builder - Construye comandos curl para probar endpoints e inspeccionar códigos de estado