Errores

Formato de respuesta de error

Todos los errores de la API devuelven un objeto JSON con un campo error:

{
  "error": "Human-readable error message"
}

Algunos errores pueden incluir un campo opcional code para manejo programático:

{
  "error": "Correo ya registrado",
  "code": "DUPLICATE_EMAIL"
}

Códigos de estado HTTP

Errores de validación (400)

Los cuerpos de las solicitudes se validan usando esquemas Zod. Cuando la validación falla, la API devuelve el primer mensaje de error de validación:

{
  "error": "El nombre es requerido"
}

Errores de validación comunes:

Errores de autenticación (401)

Se devuelve cuando no se encuentra una sesión válida:

{
  "error": "No autorizado"
}

Solución: Asegúrate de incluir la cookie next-auth.session-token. Consulta la guía de Autenticación.

Errores de permisos (403)

Se devuelve en dos casos:

Permisos de rol insuficientes:

{
  "error": "Sin permisos"
}

El rol del usuario autenticado no tiene el permiso requerido. Consulta la matriz de permisos.

Función restringida por plan:

{
  "error": "Función disponible en el plan Pro"
}

La función requiere un plan PRO. Actualiza tu plan para acceder a ella.

No encontrado (404)

Se devuelve cuando un recurso no existe o pertenece a otro tenant:

{
  "error": "Cotización no encontrada"
}

Como la API aplica aislamiento por tenant, recibirás un 404 (no un 403) al intentar acceder a recursos de otro tenant.

Conflicto (409)

Se devuelve cuando se violaría una restricción de unicidad:

{
  "error": "Ya existe un producto con ese SKU"
}

Buenas prácticas

1. Siempre verifica el código de estado — no asumas que la solicitud fue exitosa
2. Analiza el campo error — contiene un mensaje legible para el usuario (en español)
3. Maneja el 401 re-autenticándote — las cookies de sesión expiran
4. Maneja el 403 verificando rol/plan — no todos los usuarios pueden acceder a todos los endpoints
5. Maneja el 400 mostrando el mensaje de validación — le indica al usuario exactamente qué debe corregir