Errores y Códigos HTTP

Esta sección describe los códigos de error HTTP y el formato de respuestas de error de la API.

Códigos HTTP

Respuestas Exitosas

Código	Nombre	Descripción
200	OK	Solicitud exitosa
201	Created	Recurso creado exitosamente
204	No Content	Éxito sin contenido (DELETE)

Errores del Cliente

Código	Nombre	Descripción
400	Bad Request	Datos de entrada inválidos
401	Unauthorized	Autenticación requerida o inválida
403	Forbidden	Sin permisos para el recurso
404	Not Found	Recurso no encontrado
409	Conflict	Conflicto con estado actual
422	Unprocessable Entity	Datos válidos pero no procesables
429	Too Many Requests	Rate limit excedido

Errores del Servidor

Código	Nombre	Descripción
500	Internal Server Error	Error interno del servidor
502	Bad Gateway	Error de servidor upstream
503	Service Unavailable	Servicio temporalmente no disponible

Formato de Errores

La API conserva más de un formato por compatibilidad. No asuma un único shape global sin revisar el endpoint.

Estructura Legacy

{
  "success": false,
  "message": "Descripción general del error",
  "errors": [
    {
      "field": "campo_afectado",
      "message": "Descripción específica"
    }
  ]
}

Estructura con Código de Dominio

{
  "error": {
    "code": "SLOT_CAPACITY_FULL",
    "message": "El slot ya alcanzó su capacidad"
  }
}

Ejemplos por Código

400 Bad Request

{
  "success": false,
  "message": "Error de validación",
  "errors": [
    {
      "field": "email",
      "message": "El email debe ser válido"
    },
    {
      "field": "password",
      "message": "La contraseña debe tener al menos 8 caracteres"
    }
  ]
}

401 Unauthorized

{
  "success": false,
  "message": "Token no proporcionado"
}

{
  "success": false,
  "message": "Token expirado"
}

403 Forbidden

{
  "success": false,
  "message": "No tiene permisos para acceder a este recurso"
}

404 Not Found

{
  "success": false,
  "message": "Recurso no encontrado"
}

409 Conflict

{
  "success": false,
  "message": "El email ya está registrado"
}

429 Rate Limited

{
  "success": false,
  "message": "Demasiadas solicitudes. Intente en 15 minutos.",
  "retryAfter": 900
}

500 Internal Server Error

{
  "success": false,
  "message": "Error interno del servidor"
}

Modo Producción

En producción, los errores 500 no exponen detalles internos por seguridad.

Manejo de Errores

Estrategia Recomendada

flowchart TD
  A[Request API] --> B{Código HTTP}
  B -->|2xx| C[Procesar respuesta]
  B -->|400| D[Mostrar errores de validación]
  B -->|401| E[Redirigir a login]
  B -->|403| F[Mostrar mensaje de permisos]
  B -->|404| G[Mostrar no encontrado]
  B -->|429| H[Esperar y reintentar]
  B -->|5xx| I[Mostrar error genérico]

Código de Ejemplo

async function fetchAPI(endpoint, options = {}) {
  try {
    const response = await fetch(`${API_BASE}${endpoint}`, {
      ...options,
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${getToken()}`,
        ...options.headers
      }
    });

    const data = await response.json();

    if (!response.ok) {
      switch (response.status) {
        case 400:
          // Errores de validación
          throw new ValidationError(data.errors);

        case 401:
          // Token inválido o expirado
          clearToken();
          redirectToLogin();
          break;

        case 403:
          // Sin permisos
          throw new ForbiddenError(data.message);

        case 404:
          // No encontrado
          throw new NotFoundError(data.message);

        case 429:
          // Rate limit
          const retryAfter = data.retryAfter || 60;
          throw new RateLimitError(retryAfter);

        default:
          // Error del servidor
          throw new ServerError(data.message);
      }
    }

    return data;
  } catch (error) {
    if (error.name === 'TypeError') {
      // Error de red
      throw new NetworkError('Sin conexión');
    }
    throw error;
  }
}

Headers de Error

La API incluye headers útiles en respuestas de error:

Header	Descripción
X-RateLimit-Limit	Límite total de requests
X-RateLimit-Remaining	Requests restantes
X-RateLimit-Reset	Timestamp de reset
Retry-After	Segundos para reintentar (429)

Errores Comunes

Autenticación

Error	Causa	Solución
Token no proporcionado	Falta header	Agregar Authorization: Bearer <token>
Token inválido	Malformado	Verificar formato del token
Token expirado	Expiró	Reautenticar; la API actual no expone refresh token

Validación

Error	Causa	Solución
Email requerido	Campo vacío	Enviar email válido
Formato inválido	Datos mal formateados	Revisar esquema de la API
Valor fuera de rango	Número inválido	Verificar límites permitidos

Permisos

Error	Causa	Solución
Sin permisos	Rol insuficiente	Solicitar permisos adicionales
Recurso no permitido	Otro tenant	Verificar tenantId

---

Buena Práctica

Siempre maneje todos los códigos de error posibles en su aplicación para una mejor experiencia de usuario.