Catálogo de errores
Toda respuesta de error sigue un esquema unificado: ok=false + error.{type, message, details}. Esta sección documenta los 7 tipos tipificados, los códigos del INS y los códigos específicos de la pasarela de pago.
Tipos de error tipificados
Campos obligatorios faltantes o con formato inválido.
UX recomendado
Resaltar campos faltantes/inválidos en el formulario.
Resolución
- Revisar details.missing para identificar campos faltantes
- Revisar details.invalid para campos con formato incorrecto
- Corregir los datos y reintentar
{
"ok": false,
"error": {
"type": "VALIDATION_ERROR",
"message": "Campos obligatorios faltantes o inválidos",
"details": {
"missing": ["client.idNumber", "contact.email"],
"invalid": ["client.birthDate"]
}
}
}Intento de emisión (EMI) sin consentimiento informado.
UX recomendado
Regresar a la pantalla de consentimiento informado.
Resolución
- Presentar el texto de consentimiento informado al cliente
- Obtener aceptación explícita
- Enviar consent.accepted=true, consent.version y consent.timestamp en el request EMI
{
"ok": false,
"error": {
"type": "CONSENT_REQUIRED",
"message": "La emisión requiere consentimiento informado del cliente",
"details": {
"requiredFields": ["consent.accepted", "consent.version", "consent.timestamp"],
"consentVersion": "cyberpro-consent-v1"
}
}
}Múltiples coincidencias al resolver ubicación por nombres.
UX recomendado
Mostrar selector con las opciones de details.candidates.
Resolución
- Presentar las opciones de candidates al usuario
- Reintentar usando los códigos del candidato seleccionado (más preciso que nombres)
El INS rechazó la solicitud.
UX recomendado
Mostrar mensaje amigable; log interno para soporte.
Resolución
- Revisar details.detail para entender la causa
- Corregir los datos según el mensaje del INS
- Si persiste, contactar soporte
{
"ok": false,
"error": {
"type": "INS_ERROR",
"message": "El INS rechazó la solicitud",
"details": { "status": 400, "codigoEstado": "99", "detail": "El número de identificación no corresponde al tipo indicado" }
}
}API key inválida o no proporcionada.
UX recomendado
Error de configuración interna — no mostrar al usuario final.
Resolución
- Verificar que el header x-api-key esté incluido en el request
- Confirmar que la clave corresponde al ambiente correcto
Error de conectividad con el servicio del INS.
UX recomendado
Servicio temporalmente no disponible, intente nuevamente.
Resolución
- Reintentar después de 5 segundos (máximo 2 reintentos automáticos)
- Si persiste >15 min, contactar soporte
El INS no respondió dentro del tiempo esperado (>15s).
UX recomendado
La solicitud tardó más de lo esperado, intente nuevamente.
Resolución
- Reintentar después de 10 segundos (máximo 1 reintento)
- Si persiste, sugerir intentar más tarde
Códigos del INS (codigoEstado)
Códigos retornados por la API del INS y su mapeo a la API Ubiqs.
| codigoEstado | Significado | Mapeo Ubiqs | Acción |
|---|---|---|---|
| 00 | Operación exitosa | ok:true | Procesar respuesta normalmente |
| 2 | Deuda pendiente de aplicar (asíncrono) | ok:true (estado intermedio) | Consultar DEUDA_ESTADO con consecutivoDeuda |
| 98 | Solicitud rechazada (pago declinado) | INS_ERROR | Ver tabla de pagos para detalle por escenario |
| 99 | Error en datos enviados | INS_ERROR | Revisar detail y corregir datos |
| 500 | Error interno del servidor INS | NETWORK_ERROR / INS_ERROR | Reintentar; si persiste, escalar |
Respuestas del pago (cargo a tarjeta)
Escenarios cubiertos por la matriz PAGO con respuesta normalizada al cliente.
| Escenario | CodEstado | EsAprobada | Mensaje | Acción recomendada |
|---|---|---|---|---|
| Pago satisfactorio | 00 | 1 | APPROVED (auth#) | Continuar flujo → aplicar deuda |
| Tarjeta declinada | 98 | 0 | DECLINADA | Solicitar otra tarjeta o método de pago |
| Cuenta inválida | 98 | 0 | CUENTA INVALIDA | Verificar datos de la tarjeta |
| Fondos insuficientes | 98 | 0 | FONDOS INSUFICIENTES | Informar al cliente; sugerir otra tarjeta |
| Monto límite excedido | 98 | 0 | MONTO LIMITE EXCEDIDO | Reducir monto o usar otra tarjeta |
| Transacción inválida | 98 | 0 | TRANSACCION INVALIDA | Reintentar o escalar a soporte |
| Timeout del gateway | 500 | — | HTTP 500 | Reintentar (máximo 1 vez) |