Manejo de errores

Formato

Los errores siguen el formato estándar de la plataforma:


{
  "statusCode": 404,
  "message": "[RIPEI-PLAN-003] Plan con ID 555 no encontrado. Verifica que el ID exista y pertenezca a tu empresa.",
  "error": "Not Found"
}

statusCode — código HTTP.
message — descripción en español, accionable (qué campo falló y qué se esperaba). En errores de validación de campos puede ser un array de strings.
El prefijo [RIPEI-XXXX-NNN] es un código estable de error: si necesitas ayuda, compártelo con el equipo de Ripei — les permite ubicar el evento exacto en los logs.

Códigos HTTP

Código	Significado
`400`	Petición inválida — el `message` indica el campo y la regla que falló.
`401`	Token inválido, revocado, sin el scope requerido, o header `company` que no corresponde al token.
`404`	El recurso no existe o pertenece a otra empresa (por seguridad la API no distingue entre ambos casos).
`500`	Error interno — comparte el código `[RIPEI-…]` con soporte.

Multi-tenant estricto. Todos los IDs (grupos, clientes, planes, suscripciones, facturas) se validan contra tu empresa. Referenciar un ID de otra empresa devuelve el mismo 404 que un ID inexistente.

Prefijos de código por recurso

Prefijo	Recurso
`RIPEI-GRUP-`	Grupos familiares
`RIPEI-USER-`	Clientes (companyUsers)
`RIPEI-PLAN-`	Planes
`RIPEI-PSET-`	Configuración de cuotas
`RIPEI-SUBS-`	Suscripciones
`RIPEI-BILL-`	Facturas

Ejemplos frecuentes

Código	Causa	Solución
`RIPEI-USER-004`	Creaste un cliente con rol de grupo sin `groupId`.	Crea primero el grupo y envía su ID.
`RIPEI-USER-005`	El cliente ya tiene un registro activo en ese grupo.	No es necesario volver a crearlo.
`RIPEI-PLAN-005`	La suma de las cuotas no coincide con el monto del plan.	Ajusta `amountPerInstallment` o el `amount`.
`RIPEI-PSET-003`	Enviaste una cantidad de cuotas que no coincide con `numberOfInstallments`.	Envía 1 monto global o exactamente N montos.
`RIPEI-SUBS-005`	El cliente ya tiene una suscripción activa a ese plan.	Usa la existente o cancélala primero.
`RIPEI-BILL-003`	Creaste una factura sin `amount` ni `subscriptionId`.	Envía el monto o asocia una suscripción.