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": {
          "detail": "expectedAmount of 1000000 does not match received 12000 from transfer",
          "handle": "cre_0332WPpBnqVay67xA",
          "moment": "2026-01-26T22:33:42.542Z",
          "reason": "bridge.unexpected-error",
          "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": {
        "detail": "expectedAmount of 1000000 does not match received 12000 from transfer",
        "handle": "cre_0332WPpBnqVay67xA",
        "moment": "2026-01-26T22:33:42.542Z",
        "reason": "bridge.unexpected-error",
        "status": "failed"
    }
}

Esta proof contiene siempre la misma estructura base:

  • reason → código técnico del error
  • detail → descripción semántica del fallo
  • status → failed
  • moment → timestamp del error
  • handle → identificador del componente que falló

Errores del bridge

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

Razón del errorMensaje de errorMensaje en español (como lo envía el riel)
auth.forbidden100 - Provided token doesn't have permission to perform the operation—
auth.unauthorized101 - Unauthorized request, invalid or expired token—
bridge.unexpected-error99 - Unexpected server error
102 - Labels object is invalid or missing
103 - Transfer or action source is invalid
104 - Invalid handle
105 - Invalid signer
106 - Invalid default wallet signer address
107 - Transfer or action target is invalid
108 - Invalid symbol handle or address
109 - Invalid amount
121 - Resource doesn't exist in the system
123 - Domain rules are violated for transfer
137 - Transfer rejected due to onboarding
142 - Deadline defined by x-minka-deadline header is exceeded in the request chain
303 - Invalid access credentials at the bank
304 - Transfer information is invalid
305 - User abandoned the transaction at the bank
316 - Transactional data is not consistent
317 - Financial entity does not confirm transaction status
318 - Transaction not included in the bank
319 - Transfer was marked as fraud
321 - Transaction status changed
325 - Bank does not accept transaction initialization
326 - Private key missing
331 - Transaction deadline exceeded
332 - Unexpected error happened when calling financial entity
333 - Double credit
334 - A different amount was credited
335 - A different user was credited
336 - Unauthorized credit
337 - Unauthorized transaction		303 - Datos de acceso inválidos en el banco
304 - Información de la transferencia inválida
305 - Usuario abandonó la transacción en el banco
316 - Inconsistencia en los datos de la transacción
317 - Banco no confirma estado de la transacción
318 - Transacción no registrada por el banco
319 - Transferencia marcada como fraude
321 - Estado de la transacción ha cambiado
325 - Banco no acepta la inicialización de la transacción
331 - Plazo de transacción vencido
332 - Error no definido del banco
333 - Doble abono
334 - Se abonó un valor diferente
335 - Se abonó a un usuario diferente
336 - Crédito no autorizado
337 - Transacción no autorizada
bridge.entry-timeout120 - Request timed out
300 - Transfer timeout
323 - Transfer expired
324 - User does not show any activit in TIN (timeout)		300 - Tiempo de espera excedido
323 - Navegador del usuario no compatible con TIN
324 - Usuario inactivo en TIN (timeout)
bridge.account-insufficient-balance112 - Not enough balance
315 - Insufficient funds		315 - Fondos insuficientes
bridge.entry-rejected301 - Source has rejected the transfer
302 - Destination has rejected the transfer		301 - Fuente rechazó la transacción
302 - Destino rechazó la transferencia
bridge.account-inactive306 - Seizure account
307 - Inactive account
308 - Cancelled account
310 - Account not enabled
312 - Account paid off
320 - User does not have TIN payments enabled		306 - Cuenta embargada
307 - Cuenta inactiva
308 - Cuenta cancelada
310 - Cuenta no habilitada
312 - Cuenta saldada
320 - Usuario no tiene habilitados pagos TIN
bridge.account-not-found309 - Account does not exist
311 - Account has not being assigned		309 - Cuenta no existe
311 - Cuenta no asignada
bridge.account-limit-exceeded313 - User exceeds the transactional limit authorized by the bank
329 - Transaction limit exceeded by the user		313 - Usuario excede el límite transaccional autorizado
329 - Límite de transacción excedido por el usuario
bridge.core-unreachable314 - Bank is not available
330 - Cannot connect to the financial entity
314 - Banco no disponible
330 - No se puede conectar con el banco
bridge.fraud-detected322 - Transaction declined by fraud322 - Transacción rechazada por antifraude

Errores del core

Razón del errorMensaje de error
core.source-invalidSource of balance movement can’t be resolved to valid wallet.
core.target-invalidTarget of balance movement can’t be resolved to valid wallet.
core.symbol-invalidSymbol of balance movement can’t be resolved.
core.intent-expiredIntent 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-exceededIntent 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-failedBridge 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-unreachableUnable to deliver prepare event to bridge. Used when all attempts defined by retry strategy failed.
core.bridge-unsupported-operationUnable to send request to bridge because it doesn't support the operation.
core.routing-failedWhen 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-exceededWhen the routing of an intent is too deep. Used to avoid routing loops on wallets.
core.unexpected-errorUnexpected 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ónDescripciónEstado HTTP
record.not-foundRequested record by handle doesn't exist in the ledger database.404
record.relation-not-foundRelated record referenced in the received record <record>.data.<relation> doesn't exist in the ledger database.422
record.duplicatedRecord with same handle already exists in the ledger database.409
record.schema-invalidReceived record doesn't match the expected record schema. Also used when request path or query params doesn't match expected request schema.422
record.invalidRecord schema is correct but it cannot be processed by the server.422
record.drop-rejectedRecord drop cannot be processed by the server due to an internal validation.422
record.labels-policy-violationLabel(s) can not be processed due to policy violation.422
record.status-policy-violationStatus(es) can not be processed due to policy violation.422
record.status-quorum-not-metRecord status change cannot be performed because the quorum is not met yet.N/A
record.update-rejectedRecord 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 errorMensaje de error
bridge.unexpected-error0 - Success
100 - DICE error: You do not have sufficient privileges to perform this operation.
118 - DICE error: The NIT must be 9 digits long.
118 - DICE error: The payment method number exceeds 34 digits
118 - DICE error: The payment method type must be one of those registered in the global dictionary.
118 - DICE error: The EASPBV Receiver must be one of those registered in the global dictionary.
118 - DICE error: The document type must be one of those registered in the global dictionary.
118 - DICE error: The person type must be one of those recorded in the global dictionary.
118 - DICE error: For natural persons, at least the first and last name must be entered. The Dsplnm and Nn must be empty.
118 - 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.
118 - DICE error: The length for the name of a legal or natural person is exceeded.
118 - DICE error: The key must comply with additional rules.
118 - DICE error: Field AllowSecIDUpdate must be Y or N in DEAC operation.
118 - DICE error: The EASPBV code does not exist.
118 - DICE error: The key type must be one of those registered in the global dictionary.
118 - DICE error: The participant cannot be determined.
121 - DICE error: The key does not exist or is inactive.
123 - DICE error: The key has been canceled and does not meet the minimum number of days to register again.
123 - DICE error: The key is suspended by the customer.
123 - DICE error: The key is already registered with the same financial institution, but to a different account.
123 - DICE error: The key is already registered with another financial institution.
123 - DICE error: The key is already registered with the same account number.
123 - DICE error: The key is suspended by the participant.
123 - DICE error: Duplicate Detected
136 - DICE error: Tenant ID not found. Must be DICETEST01.
136 - DICE error: Session error.
136 - DICE error: Channel not open.
136 - DICE error: Message sent by an inappropriate channel.

123 - 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

Reason for errorError message
bridge.unexpected-error800 - MOL ERROR: General MOL error
801 - MOL ERROR U101: Tenant ID not found
802 - MOL ERROR U103: Tenant undefined validation
803 - MOL ERROR U106: Transaction not found
804 - MOL ERROR U112: Amount exceeds the maximum allowed
805 - MOL ERROR U119: Session error
806 - MOL ERROR U120: Inbound channel signed out
807 - MOL ERROR U122: Target participant not active
808 - MOL ERROR U125: Source participant not configured in the system
809 - MOL ERROR U126: Target participant not configured in the system
810 - MOL ERROR U173: SPBVI timeout error
800 - MOL ERROR U193: The balance in the Participant's liquidity account in the MOL is less than or equal to the allowed value
811 - MOL ERROR U194: Insufficient funds
812 - MOL ERROR U212: Message sent by an inappropriate channel
813 - MOL ERROR U250: Key type must be registered in global dictionary
800 - MOL ERROR U272: Error due to rules for source or target
814 - MOL ERROR U801: The participant cannot be determined
815 - MOL ERROR U804: Keys not found or inactive
816 - MOL ERROR U805: Keys suspended by customer
817 - MOL ERROR U806: Key already registered (same entity/diff account)
818 - MOL ERROR U807: Key registered by another financial entity
819 - MOL ERROR U808: Key already registered with same account number
820 - MOL ERROR U809: Insufficient privileges to perform this operation
821 - MOL ERROR U811: Key suspended by participant
822 - MOL ERROR U908: One or both participants are locked
823 - MOL ERROR B001: Source bank timeout
824 - MOL ERROR B002: Target bank timeout
825 - MOL ERROR B101: Invalid target customer's account number
826 - MOL ERROR B102: Target account validation error
827 - MOL ERROR B103: Target ID error
828 - MOL ERROR B104: Target payment method error
829 - MOL ERROR B105: Target account not found
830 - MOL ERROR B106: Fraud detection control
831 - MOL ERROR B107: Exceeds maximum low-amount deposits
832 - MOL ERROR B108: Exceeds SPBVI maximum amount
833 - MOL ERROR B109: Exceeds target bank maximum amount
834 - MOL ERROR B301: Source SPBVI timeout
835 - MOL ERROR B302: Target SPBVI timeout

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 errorCódigos PSE (detail)
bridge.account-limit-exceededFAIL_EXCEEDEDLIMIT — El cliente supera el límite transaccional autorizado por el banco
bridge.account-inactiveFAIL_DISABLEDUSEREMAIL — El correo del cliente está deshabilitado en PSE
bridge.account-not-foundFAIL_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-rejectedFAIL_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 errordetailSignificado
bridge.entry-rejectedNOT_AUTHORIZEDEl cliente no autorizó la transacción en el portal de su banco
bridge.unexpected-errorFAILEDLa 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.12.0
  • 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.0
  • Agregado• Error DICE 123 Duplicate Detected
1.4.0
  • 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.0
  • Agregado• Errores de los registros agregados
1.2.0
  • 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.0
  • Agregado• Errores del Bre-B agregados
1.0.1
  • Agregado• Errores del core agregados
1.0.0
  • Agregado• Versión inicial