Manejo de Errores

El backend de Floutic utiliza un contrato de errores estandarizado para facilitar el manejo de excepciones en el frontend y proporcionar mensajes claros al usuario final.

Contrato de Respuesta de Error

Todas las respuestas de error (4xx y 5xx) siguen el siguiente formato JSON:

{
  "detail": {
    "code": "ERROR_CODE_STRING",
    "message": "Mensaje legible para el usuario final en español."
  }
}

Campos

Campo	Tipo	Descripción
code	string	Código único identificador del error (Snake Case, Mayúsculas). Útil para lógica de frontend (ej. traducciones, redirecciones).
message	string	Mensaje descriptivo en español, listo para mostrarse en una notificación toast o alerta al usuario.

Catálogo de Errores Comunes

Errores de Pagos (Stripe)

Código	Mensaje (Ejemplo)	Causa Probable
STRIPE_INSUFFICIENT_FUNDS	"No hay saldo disponible suficiente en Stripe para completar esta operación."	La cuenta de Stripe de la plataforma no tiene fondos suficientes para realizar la transferencia.
PAYMENT_INTENT_NOT_FOUND	"No se encontró el pago en Stripe."	El ID del PaymentIntent no existe o es incorrecto.
STRIPE_TRANSFER_FAILED	"No se pudo transferir el pago al experto desde Stripe."	Fallo al intentar mover fondos a la cuenta Connect del experto.
PAYMENT_CREATION_FAILED	"No se pudo crear el pago en este momento."	Error genérico al iniciar un PaymentIntent.
PAYMENT_RELEASE_FAILED	"No se pudo liberar el pago."	Error al capturar el pago o transferir fondos.
PAYMENT_ALREADY_PROCESSED	"Este pago ya ha sido procesado."	Intento de liberar un pago que ya está en estado released o completed.

Errores de Validación de Proyecto

Código	Mensaje (Ejemplo)	Causa Probable
PROJECT_NOT_FOUND	"Proyecto no encontrado"	El ID del proyecto no existe.
NOT_ENOUGH_PERMISSIONS	"No tienes permisos suficientes"	El usuario intenta acceder a un recurso que no le pertenece.
PAYMENT_AMOUNT_EXCEEDS_BUDGET	"El importe del pago supera el presupuesto del proyecto"	La suma de pagos supera el presupuesto total.
MILESTONE_NOT_FOUND	"Hito no encontrado o no pertenece al proyecto"	ID de hito inválido.

Errores de Integración (Stripe Connect)

Código	Mensaje (Ejemplo)	Causa Probable
STRIPE_CONNECT_REQUIRED	"El experto debe completar Stripe Connect antes de recibir pagos"	El experto no ha completado el onboarding en Stripe.
STRIPE_ACCOUNT_NOT_ACTIVE	"La cuenta de Stripe del experto no está activa"	La cuenta Connect está restringida o pendiente de verificación.

Implementación en Frontend

El frontend debe parsear la respuesta de error y utilizar el campo message para mostrar feedback al usuario.

// Ejemplo de manejo en frontend
try {
  await releasePayment(paymentId);
} catch (error) {
  const { code, message } = error.response.data.detail;
  
  if (code === 'STRIPE_INSUFFICIENT_FUNDS') {
    // Lógica específica (ej. sugerir recargar saldo)
  }
  
  toast.error(message); // Mostrar mensaje amigable
}