Catálogo de errores
Todos los errores siguen el envelope universal con un objeto error: { code, name, description, message }. El code proviene del catálogo (MongoDB); el message es el detalle específico que agrega el servicio.
Catálogo de códigos (code)
| Código | Escenario real |
|---|---|
000 | Excepción no controlada (catch-all del handler). No se registra como error de negocio. |
2000 | Transacción no encontrada o en estado inválido para la operación |
2001 | Config de cliente o de banco no encontrada; transacción no encontrada (cancel/void) |
2002 | Config de banco o cuenta no encontrada (en authorize/capture) |
2003 | Monto inválido / validación de monto / processorAmount inválido / banco sin respuesta |
2004 | Usuario bloqueado; OTP inválido (en autorización de transacción) |
5000 | Error interno; el banco no soporta afiliación |
5001 | Estado de afiliación inválido recibido del banco (webhook) |
6000 | Error de cuenta; faltan parámetros (cuenta/OTP); validaciones de cuenta |
6001 | Usuario no encontrado / parámetro userUID faltante |
6002 | Crédito/saldo insuficiente (validación de usuario de crédito) |
6003 | Cuenta no encontrada |
6005 | Cuenta en mora / default |
6010 | Faltan datos de usuario / afiliación / pre-calificado, o error al crear/actualizar |
6011 | Formato de email inválido (afiliación) |
6012 | Formato de teléfono primario inválido (afiliación) |
6013 | Formato de teléfono secundario inválido (afiliación) |
6014 | Fecha de nacimiento o de expiración del documento inválida |
6015 | Género inválido (debe ser male o female) |
Estrategia de reintento
Cuándo reintentar
Ante 5000 o 000, reintenta con backoff exponencial (1s, 2s, 4s) hasta 3 veces. Los códigos 2xxx / 6xxx son de negocio y no deben reintentarse sin corregir el input.
Para el detalle por endpoint de qué códigos puede devolver cada operación, consulta la referencia interactiva de Créditos Core.