Referencia de errores

Dado que el procesamiento de intents es un proceso asincrónico, pueden ocurrir errores durante su ciclo de vida. Estos errores dependen del riel específico donde se procese el intent, pero están estandarizados como errores de Kamin Ledger.

A continuación se muestra una lista de errores de Kamin Ledger junto con una guía sobre cómo manejarlos. Los errores se categorizan en errores de usuario y errores del sistema:

Errores de usuario: generalmente pueden ser resueltos por el propio usuario.
Errores del sistema: usualmente requieren abrir un ticket de soporte con Kamin, ya que no pueden ser resueltos directamente por el usuario.

Identificar un error

Para poder validar un error, lo primero es identificar dónde se encuentra.
Los errores siempre se registran dentro de una proof en cada Intent.
La proof relevante es la primera que contiene el estado (status) failed, ya que esta representa el error raíz que origina la falla del flujo.

Usemos el siguiente ejemplo.
Esta es la estructura real de un Intent usando Bre-B que terminó en estado rejected.
Las proofs están simplificadas, pero la estructura es equivalente a la de un Intent real.

{
  "hash": "hash",
  "data": {
    "handle": "handle",
    "claims": [
      {
        "action": "transfer",
        "amount": 000,
        "source": {
          "handle": "source"
        },
        "symbol": {
          "handle": "cop"
        },
        "target": {
          "handle": "target"
        }
      }
    ],
    "schema": "transfer",
    "custom": {
      "received": "2025-01-26T08:52:22.241-05:00"
    },
    "access": [
      {...}
    ]
  },
  "luid": "$int.-1frQtSIHrnBhgsZD",
  "meta": {
    "proofs": [
      {
        "digest": "80eeb99b572eecf10db4c706c2b3adadf9f4c3d4232881772ef2475fa3f0ff7f",
        "method": "ed25519-v2",
        "public": "Oh3xliLHnYelAZbQyTEZv5jo3JNrsBiea+/6X6AxUK0=",
        "result": "MWyXG0DwcWc1iCo1tOqtnK9jUjiI3CdWZKzQxG9csklF/EahdX9RIYvKJIFljg2LLEW0Vvexs2dXStkC6Pi5CA=="
      },
      {
        "custom": {
          "moment": "2026-01-26T22:33:27.147Z",
          "status": "pending"
        },
        ...
      },
      {
        "custom": {
          "luid": "$int.-1frQtSIHrnBhgsZD",
          "moment": "2026-01-26T22:33:27.161Z",
          "status": "pending"
        },
        ...
      },
      {
        "custom": {
          "amount": 12000,
          "handle": "deb_0332WPZB68NxDfJ2a",
          "inputs": [
            0
          ],
          "moment": "2026-01-26T22:33:27.377Z",
          "schema": "debit",
          "status": "resolved",
          "symbol": "cop",
          "wallet": "kamin.one"
        },
        ...
      },
      {
        "custom": {
          "amount": 12000,
          "bridge": "transfiya",
          "handle": "cre_0332WPpBnqVay67xA",
          "inputs": [
            0
          ],
          "moment": "2026-01-26T22:33:27.378Z",
          "schema": "credit",
          "status": "resolved",
          "symbol": "cop",
          "wallet": "breb"
        },
       ...
      },
      {
        "custom": {
          "handle": "deb_0332WPZB68NxDfJ2a",
          "moment": "2026-01-26T22:33:27.927Z",
          "schema": "debit",
          "status": "prepared"
        },
        ...
      },
      {
        "custom": {
          "handle": "cre_0332WPpBnqVay67xA",
          "moment": "2026-01-26T22:33:27.927Z",
          "schema": "credit",
          "status": "prepared"
        },
        ...
      },
      {
        "custom": {
          "reason": "bridge.unexpected-error",
          "detail": "Inconsistencia en los datos de la transacción",
          "status": "failed",
          ...
        },
        ...
      },
      {
        "custom": {
          "detail": "Bridge(s) failed to process intent: transfiya",
          "moment": "2026-01-26T22:33:43.066Z",
          "reason": "core.bridge-prepare-failed",
          "status": "failed"
        },
        ...
      },
      {
        "custom": {
          "moment": "2026-01-26T22:33:43.180Z",
          "status": "aborted"
        },
        ...
      },
      {
        "custom": {
          "coreId": "0332WSmQYFxIr2goI",
          "handle": "cre_0332WPpBnqVay67xA",
          "moment": "2026-01-26T22:33:44.788Z",
          "status": "aborted"
        },
        ...
      },
      {
        "custom": {
          "handle": "deb_0332WPZB68NxDfJ2a",
          "moment": "2026-01-26T22:33:48.639Z",
          "schema": "debit",
          "status": "aborted"
        },
        ...
      },
      {
        "custom": {
          "handle": "cre_0332WPpBnqVay67xA",
          "moment": "2026-01-26T22:33:48.639Z",
          "schema": "credit",
          "status": "aborted"
        },...
      },
      {
        "custom": {
          "moment": "2026-01-26T22:33:48.998Z",
          "status": "rejected"
        },
        ...
      }
    ],
    "status": "rejected",
    "thread": "-1frQtPMwBM6aQU0t",
    "moment": "2026-01-26T22:33:27.146Z",
    "owners": []
  }
}

Lo importante de este ejemplo son las proofs que tienen el estado failed. Para identificar la razón real del fallo, se debe tomar la primera proof con status = failed, ya que esta corresponde al error causal y no a los errores derivados del sistema.

En este caso, la proof relevante es:

{
    "custom": {
        "reason": "bridge.unexpected-error",
        "detail": "Inconsistencia en los datos de la transacción",
        "status": "failed",
        ...
    }
}

Esta proof contiene siempre la misma estructura base:

reason → razón técnica del error
detail → descripción semántica del fallo
status → failed

Errores del bridge

La columna en español existe porque el riel no es consistente con el idioma: el mismo error puede llegar con su mensaje en español o en inglés, según el participante que lo envíe. Empareja por la razón (reason), nunca por el texto del mensaje.

Razón del error	Mensaje de error	Mensaje en español (como lo envía el riel)
auth.forbidden	Provided token doesn't have permission to perform the operation	—
auth.unauthorized	Unauthorized request, invalid or expired token	—
bridge.unexpected-error	Unexpected server error	—
	Labels object is invalid or missing	—
	Transfer or action source is invalid	—
	Invalid handle	—
	Invalid signer	—
	Invalid default wallet signer address	—
	Transfer or action target is invalid	—
	Invalid symbol handle or address	—
	Invalid amount	—
	Resource doesn't exist in the system	—
	Domain rules are violated for transfer	—
	Transfer rejected due to onboarding	—
	Deadline defined by x-minka-deadline header is exceeded in the request chain	—
	Invalid access credentials at the bank	Datos de acceso inválidos en el banco
	User abandoned the transaction at the bank	Usuario abandonó la transacción en el banco
	Transactional data is not consistent	Inconsistencia en los datos de la transacción
	Financial entity does not confirm transaction status	Banco no confirma estado de la transacción
	Transaction not included in the bank	Transacción no registrada por el banco
	Transfer was marked as fraud	Transferencia marcada como fraude
	Transaction status changed	Estado de la transacción ha cambiado
	Bank does not accept transaction initialization	Banco no acepta la inicialización de la transacción
	Private key missing	—
	Transaction deadline exceeded	Plazo de transacción vencido
	Unexpected error happened when calling financial entity	Error no definido del banco
	Double credit	Doble abono
bridge.transfer-information-invalid	Transfer information is invalid	Información de la transferencia inválida
bridge.entry-timeout	Request timed out	—
	Transfer timeout	Tiempo de espera excedido
	Transfer expired	Navegador del usuario no compatible con TIN
	User does not show any activit in TIN (timeout)	Usuario inactivo en TIN (timeout)
bridge.account-insufficient-balance	Not enough balance	—
bridge.account-insufficient-balance	Insufficient funds	Fondos insuficientes
bridge.entry-rejected	Source has rejected the transfer	Fuente rechazó la transacción
bridge.entry-rejected	Destination has rejected the transfer	Destino rechazó la transferencia
bridge.account-inactive	Seizure account	Cuenta embargada
	Cancelled account	Cuenta cancelada
	Account not enabled	Cuenta no habilitada
	Account paid off	Cuenta saldada
	User does not have TIN payments enabled	Usuario no tiene habilitados pagos TIN
bridge.account-not-found	Account does not exist	Cuenta no existe
bridge.account-not-found	Account has not being assigned	Cuenta no asignada
bridge.account-limit-exceeded	User exceeds the transactional limit authorized by the bank	Usuario excede el límite transaccional autorizado
bridge.account-limit-exceeded	Transaction limit exceeded by the user	Límite de transacción excedido por el usuario
bridge.core-unreachable	Bank is not available	Banco no disponible
bridge.core-unreachable	Cannot connect to the financial entity	No se puede conectar con el banco
bridge.fraud-detected	Transaction declined by fraud	Transacción rechazada por antifraude

Errores del core

Razón del error	Mensaje de error
core.source-invalid	Source of balance movement can’t be resolved to valid wallet.
core.target-invalid	Target of balance movement can’t be resolved to valid wallet.
core.symbol-invalid	Symbol of balance movement can’t be resolved.
core.intent-expired	Intent expired before all required signatures are collected. Signature with this `reason` is added to intent by a background job which periodically checks intents and aborts all which are still `pending` after predefined timeout.
core.limit-exceeded	Intent execution exceeded a limit. Limits can be exceeded either by source or target wallet and for different reasons. The `detail` of the error will contain more details. This error shows when there is not enought balance to do an Intent
core.bridge-prepare-failed	Bridge reported fail in `prepare` phase. When ledger core adds a signature with this `reason` it will set `failId` to the `reason` received in `failed` signature from a bridge.
core.bridge-unreachable	Unable to deliver `prepare` event to bridge. Used when all attempts defined by retry strategy failed.
core.bridge-unsupported-operation	Unable to send request to bridge because it doesn't support the operation.
core.routing-failed	When the routing of an intent couldn't be performed. For example, when the target wallet has routes defined but none of them matches the current intent.
core.thread-size-exceeded	When the routing of an intent is too deep. Used to avoid routing loops on wallets.
core.unexpected-error	Unexpected error happened in ledger core when processing intent.

Errores de los registros

Errores relacionados con los registros del ledger. Se utilizan cuando algo está mal con los registros solicitados o enviados.

Estos errores ocurren durante el procesamiento de solicitudes de la API, por lo que también tienen códigos de estado HTTP de respuesta asociados.

Razón	Descripción	Estado HTTP
record.not-found	Requested record by handle doesn't exist in the ledger database.	404
record.relation-not-found	Related record referenced in the received record `<record>.data.<relation>` doesn't exist in the ledger database.	422
record.duplicated	Record with same handle already exists in the ledger database.	409
record.schema-invalid	Received record doesn't match the expected record schema. Also used when request path or query params doesn't match expected request schema.	422
record.invalid	Record schema is correct but it cannot be processed by the server.	422
record.drop-rejected	Record drop cannot be processed by the server due to an internal validation.	422
record.labels-policy-violation	Label(s) can not be processed due to policy violation.	422
record.status-policy-violation	Status(es) can not be processed due to policy violation.	422
record.status-quorum-not-met	Record status change cannot be performed because the quorum is not met yet.	N/A
record.update-rejected	Record update cannot be processed by the server due to an internal validation.	422

Errores de Bre-B

Los errores en Bre-B se dividen en dos categorías: errores del DICE (operaciones de las llaves) y errores del MOL (operaciones de transacciones).

Errores de DICE

Razón del error	Mensaje de error
bridge.unexpected-error	Success
	DICE error: You do not have sufficient privileges to perform this operation.
	DICE error: The NIT must be 9 digits long.
	DICE error: The payment method number exceeds 34 digits
	DICE error: The payment method type must be one of those registered in the global dictionary.
	DICE error: The EASPBV Receiver must be one of those registered in the global dictionary.
	DICE error: The document type must be one of those registered in the global dictionary.
	DICE error: The person type must be one of those recorded in the global dictionary.
	DICE error: For natural persons, at least the first and last name must be entered. The Dsplnm and Nn must be empty.
	DICE error: For legal entities, the name in the Dsplnm and Nn must be the same. The first and last names fields for natural persons must be empty.
	DICE error: The length for the name of a legal or natural person is exceeded.
	DICE error: The key must comply with additional rules.
	DICE error: Field AllowSecIDUpdate must be Y or N in DEAC operation.
	DICE error: The EASPBV code does not exist.
	DICE error: The key type must be one of those registered in the global dictionary.
	DICE error: The participant cannot be determined.
	DICE error: The key does not exist or is inactive.
	DICE error: The key has been canceled and does not meet the minimum number of days to register again.
	DICE error: The key is suspended by the customer.
	DICE error: The key is already registered with the same financial institution, but to a different account.
	DICE error: The key is already registered with another financial institution.
	DICE error: The key is already registered with the same account number.
	DICE error: The key is suspended by the participant.
	DICE error: Duplicate Detected
	DICE error: Tenant ID not found. Must be DICETEST01.
	DICE error: Session error.
	DICE error: Channel not open.
	DICE error: Message sent by an inappropriate channel.

DICE error: Duplicate Detected reporta una acción duplicada, no un registro duplicado. Aparece cuando una segunda solicitud para una operación sobre una llave llega mientras la primera aún se está procesando (por ejemplo, al reintentar la eliminación de una llave antes de que la original termine). La duplicada se ignora y la solicitud original continúa.

Errores de MOL

Razón del error	Mensaje de error
bridge.unexpected-error	MOL ERROR: General MOL error
	MOL ERROR U101: Tenant ID not found
	MOL ERROR U103: Tenant undefined validation
	MOL ERROR U106: Transaction not found
	MOL ERROR U112: Amount exceeds the maximum allowed
	MOL ERROR U119: Session error
	MOL ERROR U120: Inbound channel signed out
	MOL ERROR U122: Target participant not active
	MOL ERROR U125: Source participant not configured in the system
	MOL ERROR U126: Target participant not configured in the system
	MOL ERROR U173: SPBVI timeout error
	MOL ERROR U193: The balance in the Participant's liquidity account in the MOL is less than or equal to the allowed value
	MOL ERROR U194: Insufficient funds
	MOL ERROR U212: Message sent by an inappropriate channel
	MOL ERROR U250: Key type must be registered in global dictionary
	MOL ERROR U272: Error due to rules for source or target
	MOL ERROR AB05: Rejected Message Credit Response Out of TimeActualizado
	MOL ERROR B999: MOL ERROR B999 Unexpected errorActualizado
	MOL ERROR BE06: No se pudo validar la llave en directorioActualizado
	MOL ERROR MD02: Error interno del servicioActualizado
	MOL ERROR NT40: La transacción no se pudo procesar o ya se encuentra registradaActualizado
	MOL ERROR NT46: Service UnavailableActualizado
	MOL ERROR U801: The participant cannot be determined
	MOL ERROR U804: Keys not found or inactive
	MOL ERROR U805: Keys suspended by customer
	MOL ERROR U806: Key already registered (same entity/diff account)
	MOL ERROR U807: Key registered by another financial entity
	MOL ERROR U808: Key already registered with same account number
	MOL ERROR U809: Insufficient privileges to perform this operation
	MOL ERROR U811: Key suspended by participant
	MOL ERROR U908: One or both participants are locked
	MOL ERROR B001: Source bank timeout
	MOL ERROR B002: Target bank timeout
	MOL ERROR B101: Invalid target customer's account numberActualizado
	MOL ERROR B102: Target account validation error
	MOL ERROR B103: Target ID error
	MOL ERROR B104: Target payment method error
	MOL ERROR B105: Target account not found
	MOL ERROR B106: Fraud detection control
	MOL ERROR B107: Exceeds maximum low-amount deposits
	MOL ERROR B108: Exceeds SPBVI maximum amount
	MOL ERROR B109: Exceeds target bank maximum amount
	MOL ERROR B301: Source SPBVI timeout
	MOL ERROR B302: Target SPBVI timeout
	MOL ERROR B004: Technical error in the source SPBVIActualizado
	MOL ERROR B005: Technical error in the target SPBVIActualizado
	MOL ERROR B006: Technical error in the target bank
	MOL ERROR B113: QR code has already been used
	MOL ERROR B114: Invalid QR codeActualizado
	MOL ERROR U111: Minimum amount validation failed
	MOL ERROR U204: Liquidity Position State Not Found
bridge.entry-timeout	MOL ERROR B009: Payment order arrived out of time at receiving SPBVI
bridge.entry-timeout	MOL ERROR B003: Time-Out declared by the target bank
bridge.entry-rejected	MOL ERROR B112: Required information missing at target SPBVI
	MOL ERROR B110: Authorization failed at the target bank
	MOL ERROR B111: Required information missing at source SPBVI

Errores de cuenta a cuenta (A2A)

Cuando un participante rechaza una transferencia cuenta a cuenta, el proof failed trae el mensaje de rechazo que define ACH, en español, y la razón de error de Kamin a la que se mapea.

Razón del error	Mensaje de error
bridge.account-inactive	Cuenta inactivaNuevo
	Cuenta embargadaActualizado
	Cuenta canceladaActualizado
	Cuenta no asignadaNuevo
	Cuenta saldadaActualizado
bridge.account-limit-exceeded	Topes transaccionales excedidosNuevo
bridge.core-unreachable	Banco fuera de servicio por mantenimiento o indisponibilidadNuevo
bridge.entry-duplicated	Ya existe una transaccion registrada con el mismo idNuevo
bridge.core-invalid-access	Error de acceso invalido en bancoNuevo
bridge.transfer-information-invalid	La informacion de la transferencia no es validaNuevo
bridge.fraud-detected	Transaccion rechazada por prevencion fraude en BancoNuevo
bridge.entry-timeout	TimeoutNuevo
bridge.unexpected-core-error	Error interno en el bancoNuevo
bridge.unexpected-core-error	Error no identificado en el bancoNuevo
bridge.unexpected-error	Error inesperado durante el procesamiento de transaccionNuevo
bridge.account-not-found	Identificacion no coincide con la cuentaActualizado
	Cuenta no existeNuevo
	Numero de identificación erradoNuevo
bridge.entry-rejected	Cuenta o Deposito Electronico No Habilitado para recibir transaccionesNuevo
bridge.account-insufficient-balance	Fondos insuficientesNuevo

Errores del PSE

Cuando PSE rechaza una transacción, el proof failed lleva el código de retorno de PSE en custom.detail y el reason mapeado a las categorías estándar de Kamin en custom.reason. El rechazo ocurre en dos fases distintas del ciclo de vida del intent, cada una con su propio conjunto disjunto de valores en custom.detail:

Rechazo en la creación — Durante el registro con PSE, antes de que se entregue pseUrl. El cliente nunca es redirigido al banco. custom.detail siempre es un código FAIL_*.
Rechazo en el procesamiento de la transacción — Tras el proof confirmed del comercio, cuando PSE reporta que la transacción no fue autorizada. custom.detail es FAILED (el default del bridge cuando no hay código mapeable) o NOT_AUTHORIZED (el cliente no autorizó en su banco).

Proof failed en la creación:

  "data": {
    "reason": "bridge.entry-rejected",
    "custom": {
      "detail": "FAIL_INVALIDPARAMETERS",
      "status": "failed"
    }
  }

Proof failed en el procesamiento de la transacción:

  "data": {
    "reason": "bridge.entry-rejected",
    "custom": {
      "detail": "NOT_AUTHORIZED",
      "status": "failed"
    }
  }

Rechazos en la creación (antes del proof registered):

Razón del error	Códigos PSE (`detail`)
bridge.account-limit-exceeded	`FAIL_EXCEEDEDLIMIT` — El cliente supera el límite transaccional autorizado por el banco
bridge.account-inactive	`FAIL_DISABLEDUSEREMAIL` — El correo del cliente está deshabilitado en PSE
bridge.account-not-found	`FAIL_ENTITYNITEXISTSORDISABLED` — El NIT de la entidad no existe o está deshabilitado `FAIL_BANKNOTEXISTSORDISABLED` — El banco no existe o está deshabilitado `FAIL_SERVICENOTEXISTSORNOTCONFIGURED` — El código de servicio no existe o no está configurado
bridge.entry-rejected	`FAIL_TRANSACTIONNOTALLOWED` — La transacción no está permitida `FAIL_INVALIDPARAMETERS` — Parámetros inválidos en la solicitud `FAIL_CANNOTGETCURRENTCYCLE` — No se pudo obtener el ciclo actual de liquidación `FAIL_INVALIDAMOUNTORVATAMOUNT` — Monto o IVA inválidos

Rechazos en el procesamiento de la transacción (tras el proof confirmed):

Razón del error	`detail`	Significado
bridge.entry-rejected	`NOT_AUTHORIZED`	El cliente no autorizó la transacción en el portal de su banco
bridge.unexpected-error	`FAILED`	La transacción falló sin causa específica — el default que envía el bridge cuando no hay código PSE mapeable; no requiere escalación

Historial de cambios

1.16.123 de oct de 2026

Cambiado• Errores A2A: `Identificacion no coincide con la cuenta` ahora corresponde a `bridge.account-not-found`, y `Cuenta embargada`, `Cuenta cancelada` y `Cuenta saldada` a `bridge.account-inactive`, por requerimiento del regulador

1.16.016 de oct de 2026

Agregado• Errores MOL AB05, B999, BE06, MD02, NT40 y NT46, tal como llegan en producción
Cambiado• Errores MOL B004, B005, B101 y B114 actualizados según lo que llega en producción
Eliminado• Se eliminaron los códigos de error numéricos, ya que no eran estándar y no se enviaban en las respuestas

1.15.015 de oct de 2026

Agregado• Sección de errores de cuenta a cuenta (A2A) con los mensajes de rechazo de ACH
Eliminado• Errores del bridge reemplazados por los de la sección de A2A
Cambiado• Tablas de errores del bridge, DICE, MOL y A2A con una fila por mensaje y columnas de razón y mensaje
Cambiado• Ejemplo de proof `failed` con la estructura base `reason`, `detail` y `status`

1.14.010 de sept de 2026

Cambiado• Código 304 movido de `bridge.unexpected-error` a la nueva razón `bridge.transfer-information-invalid`

1.13.002 de sept de 2026

Agregado• Nuevos códigos de error de MOL 836 a 847 en la tabla de errores de MOL, marcados como nuevos

1.12.028 de jul de 2026

Agregado• Códigos 303, 305 y 333 a 337 en `bridge.unexpected-error`
Corregido• Se unificó la fila duplicada de `bridge.account-inactive` y se separó el código 102
Agregado• Columna con el mensaje en español y nota de que el riel no estandariza el idioma

1.11.024 de jul de 2026

Agregado• Error DICE 123 Duplicate Detected

1.4.021 de abr de 2026

Agregado• Sección de errores de PSE
Agregado• Nuevos códigos de error MOL U193 y U272
Corregido• Correcciones de texto en errores MOL

1.3.019 de mar de 2026

Agregado• Errores de los registros agregados

1.2.027 de ene de 2026

Obsoleto• Error core.insufficient-balance eliminado al no aplicar en los casos de uso actuales
Agregado• Se agrego la seccion de Identificar un error

1.1.025 de nov de 2025

Agregado• Errores del Bre-B agregados

1.0.122 de oct de 2025

Agregado• Errores del core agregados

1.0.001 de jun de 2025

Agregado• Versión inicial

Referencia de errores

On this page