Saltar al contenido principal

Códigos de Estado HTTP

🎯 Objetivo​

Regla​

4.1: Se debe comprender y utilizar correctamente los códigos de estado HTTP para comunicar de manera efectiva y estandarizada el resultado de las solicitudes de los clientes. 4.2: Los códigos de estado son una parte esencial y obligatoria de los mensajes auto-descriptivos en REST.

📖 Concepto y Definición​

Regla​

4.3: Los códigos de estado HTTP son códigos numéricos de tres dígitos que el servidor debe incluir en cada respuesta para indicar el resultado del procesamiento de la solicitud. 4.4: Estos códigos se agrupan en cinco clases, identificadas por su primer dígito, y deben usarse según su semántica definida:

  • 1xx (Informacional): Solicitud recibida, proceso continúa. (Uso poco común en APIs REST típicas, no deben ser el resultado final habitual).
  • 2xx (Éxito): Solicitud recibida, entendida y aceptada exitosamente. Debe usarse para indicar éxito.
  • 3xx (Redirección): Se requieren acciones adicionales (usualmente redirección). Debe usarse para indicar redirección o no modificación basada en caché.
  • 4xx (Error del Cliente): La solicitud tiene un error aparente del cliente (sintaxis, semántica, autorización, recurso no encontrado). Debe usarse para indicar errores atribuibles al cliente.
  • 5xx (Error del Servidor): El servidor falló al procesar una solicitud válida debido a un error interno. Debe usarse para indicar fallos del servidor.

🤔 ¿Por qué es Importante? / Beneficios Clave (Contexto)​

  • Comunicación Clara y Estandarizada: Códigos de estado proporcionan una forma universal de entender el resultado.
  • Manejo de Errores Eficiente por Cliente: Clientes pueden tomar decisiones basadas en el código.
  • Habilitan Comportamiento de Infraestructura: Proxies, cachés interpretan códigos de estado.
  • Mejora la Depuración: Códigos precisos ayudan a diagnosticar problemas.
  • Parte de la Interfaz Uniforme: Contribuyen a mensajes auto-descriptivos.

✅ Buenas Prácticas y Recomendaciones Clave​

Regla​

Do's (Uso Obligatorio de Códigos Específicos):

  • Éxito (2xx):

    • 200 OK: Debe ser la respuesta estándar para GET exitoso y PUT/PATCH exitoso si se devuelve el recurso actualizado. Puede usarse para DELETE si la respuesta incluye un cuerpo de confirmación.
    • 201 Created: Debe usarse exclusivamente después de un POST exitoso que crea un nuevo recurso. La respuesta debe incluir un encabezado Location con la URI del nuevo recurso. Puede incluir el recurso creado en el cuerpo.
    • 202 Accepted: Debe usarse cuando una solicitud es aceptada para procesamiento asíncrono que aún no ha finalizado. La respuesta puede incluir información sobre cómo verificar el estado.
    • 204 No Content: Debe usarse cuando la solicitud fue procesada exitosamente pero no hay contenido que devolver en el cuerpo. Es la respuesta preferida para DELETE exitoso o para PUT/PATCH que no devuelven el recurso. La respuesta NO DEBE incluir un cuerpo.

  • Redirección (3xx):

    • 301 Moved Permanently: Debe usarse para indicar que un recurso se ha movido permanentemente. Debe incluir el encabezado Location con la nueva URI.
    • 304 Not Modified: Debe usarse en respuesta a una solicitud GET condicional (con If-None-Match o If-Modified-Since) cuando el recurso no ha cambiado. La respuesta NO DEBE incluir un cuerpo.

  • Error del Cliente (4xx):

    • 400 Bad Request: Debe usarse como error genérico del cliente para solicitudes malformadas, con datos inválidos (no de validación de esquema) o semánticamente incorrectas. Debe acompañarse de un cuerpo de respuesta explicando el error (ver Sección 11).
    • 401 Unauthorized: Debe usarse cuando el cliente intenta acceder a un recurso protegido sin credenciales o con credenciales inválidas. La respuesta debería incluir un encabezado WWW-Authenticate.
    • 403 Forbidden: Debe usarse cuando el cliente está autenticado pero no tiene permisos para la acción/recurso solicitado. Re-autenticarse no debe cambiar el resultado.
    • 404 Not Found: Debe usarse cuando el recurso solicitado no existe.
    • 405 Method Not Allowed: Debe usarse cuando el método HTTP usado no está permitido para el recurso. La respuesta debe incluir un encabezado Allow con los métodos permitidos.
    • 409 Conflict: Debe usarse cuando la solicitud no puede procesarse debido a un conflicto con el estado actual del recurso (ej. creación duplicada, edición conflictiva).
    • 415 Unsupported Media Type: Debe usarse si el Content-Type de la solicitud no es soportado por el servidor.
    • 422 Unprocessable Entity: Debe usarse cuando la solicitud está bien formada sintácticamente pero contiene errores semánticos (ej. fallos de validación de negocio). Es preferible a 400 para errores de validación explícitos. Debe acompañarse de un cuerpo detallando los errores (ver Sección 11).
    • 429 Too Many Requests: Debe usarse para indicar que se ha excedido el límite de tasa (rate limiting). La respuesta puede incluir un encabezado Retry-After.

  • Error del Servidor (5xx):

    • 500 Internal Server Error: Debe usarse como error genérico del servidor cuando algo falla internamente y no hay un código 5xx más específico. No debe exponer detalles sensibles en la respuesta.
    • 503 Service Unavailable: Debe usarse cuando el servidor no está disponible temporalmente (mantenimiento, sobrecarga). La respuesta puede incluir un encabezado Retry-After.

Don'ts (Prohibido):

  • 4.5: No se debe usar 200 OK (o cualquier código 2xx) para indicar un error. El código de estado debe reflejar el error.
    • Prohibido: 200 OK con {"error": "Usuario no encontrado"}.
  • 4.6: No se debe usar 400 o 500 de forma genérica si existe un código de error más específico aplicable.
  • 4.7: No se deben devolver stack traces o información interna sensible en las respuestas de error 5xx (ni 4xx) enviadas al cliente.
  • 4.8: No se deben usar códigos de estado no estándar a menos que sea absolutamente necesario y esté bien documentado. Se debe priorizar el uso de códigos estándar para interoperabilidad.

💡 Ejemplos Prácticos (Ilustrativos)​

  • GET /users/123
    • Éxito: 200 OK (Norma 4.4 - 2xx)
    • No encontrado: 404 Not Found (Norma 4.4 - 4xx)
    • No autenticado: 401 Unauthorized (Norma 4.4 - 4xx)
    • Sin permiso: 403 Forbidden (Norma 4.4 - 4xx)
  • POST /users
    • Creado: 201 Created (+ Location header) (Norma 4.4 - 2xx)
    • Datos inválidos: 422 Unprocessable Entity (+ cuerpo de error) (Norma 4.4 - 4xx)
    • Email ya existe: 409 Conflict (Norma 4.4 - 4xx)
  • DELETE /users/123
    • Eliminado: 204 No Content (Norma 4.4 - 2xx)
    • No encontrado: 404 Not Found (Norma 4.4 - 4xx)
  • GET /products (con If-None-Match: "etag-xyz")
    • No modificado: 304 Not Modified (Norma 4.4 - 3xx)

🛠️ Herramientas y Consideraciones Adicionales (Contexto)​

  • RFCs relevantes: Son la fuente autoritativa.
  • Cuerpo de Respuesta en Errores: Como se norma en la Sección 11, se debe incluir un cuerpo de respuesta estructurado (JSON) para errores 4xx y 5xx que proporcione detalles útiles (código de error interno, mensaje, detalles específicos, enlace a documentación).