Lista de errores de Bank Transfer

Formato del error

{
  "type": "https://errors.lerian.studio/v1/BTF-0203",
  "title": "Conflict",
  "status": 409,
  "detail": "this initiation has already been processed",
  "code": "BTF-0203",
  "category": "deterministic",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin",
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d"
}

Definiciones de los campos

type – Un URI que identifica el código del error: https://errors.lerian.studio/v1/<code>.
title – El texto del estado HTTP.
status – El código de estado HTTP.
detail – Una explicación legible de este error.
code – Un identificador estable para el error (por ejemplo, BTF-0010).
requestId – ID de correlación de la solicitud. Presente incluso cuando está vacío. Inclúyelo en las solicitudes de soporte.
service – El servicio o dominio que produjo el error (por ejemplo, plugin, crm, midaz, fees, jd_spb).
category – Categoría de error legible por máquina para decisiones de reintento: deterministic, transient, rate_limit o plugin.
errors – Opcional. Una entrada para cada campo rechazado, con message y location (body.<field> o query.<field>).
upstream – Opcional. El código de error que devolvió un proveedor externo, como JD SPB. Está en upstream.code, sin cambios.

Errores de Bank Transfer

Los siguientes errores pueden ocurrir al interactuar con los endpoints de Bank Transfer. Cada error sigue nuestra estructura estándar. Consulta las tablas siguientes para ver la lista de posibles códigos de error, qué significan y cómo resolverlos.

202

`code`	Nombre	Descripción
BTF-9010	Transferencia escalada a la conciliación	El avance del TED OUT falló, y el plugin escaló la transferencia a la conciliación. La retención en Midaz sigue intacta. Consulta `GET /v1/transfers/{transferId}` hasta obtener el estado final. El cuerpo es un documento de problema, no una respuesta de transferencia.

400

`code`	Nombre	Descripción
BTF-0001	Entrada inválida	La solicitud contiene campos inválidos. Revisa los detalles de los campos a continuación.
BTF-0210	Motivo de retención inválido	El filtro de motivo de retención está fuera del vocabulario declarado.
BTF-0214	Estado de retención inválido	El filtro `state` no es `open`, `closed` ni `all`.

401

`code`	Nombre	Descripción
BTF-0401	No autorizado	Falló la autenticación. El token falta, es inválido o expiró.

403

`code`	Nombre	Descripción
BTF-0403	Licencia inválida	La organización no tiene licencia. Contacta a soporte para activar tu licencia.
BTF-0405	Prohibido	Permisos insuficientes para hacer esta acción.
BTF-0406	Identidad de operador requerida	El token no identifica a una persona (una cuenta de servicio o un token de otro tipo), así que el plugin no puede atribuir esta escritura manual a un operador. Ningún permiso lo resuelve. Llama al endpoint con un token de usuario.
BTF-0408	Tenant suspendido	El tenant manager le negó a este tenant el acceso al servicio.

404

`code`	Nombre	Descripción
BTF-0200	Transferencia no encontrada	Transferencia no encontrada
BTF-0201	Iniciación no encontrada	Iniciación no encontrada o pertenece a otra organización
BTF-0215	Entrada no liquidada no encontrada	El mensaje no tiene nada que un operador pueda cerrar. Un mensaje que no existe devuelve el mismo código.
BTF-0306	Webhook no encontrado	El registro de webhook no existe o pertenece a otro tenant.
BTF-0404	Organización fuera del tenant	`X-Organization-Id` indica una organización que este tenant no opera.
BTF-0407	Tenant no encontrado	El tenant manager no conoce el tenant que indica el token.
BTF-0500	Cuenta no encontrada	La cuenta del remitente no existe en el CRM
BTF-1092	Artefacto de firma no encontrado	No se encontró el artefacto de firma.
BTF-2001	Cuenta de Midaz no encontrada	No se encontró la cuenta de Midaz.

409

`code`	Nombre	Descripción
BTF-0012	Transferencia duplicada	Transferencia duplicada detectada
BTF-0016	Solicitud de idempotencia en curso	Una solicitud con esta clave `X-Idempotency` todavía mantiene la clave reservada. Mientras la primera solicitud sigue en ejecución, reenvía la solicitud idéntica después del intervalo de `Retry-After`. Si una solicitud anterior con esta clave respondió 5xx, no llega ninguna respuesta de ella: lee el recurso y envía el trabajo con una clave nueva solo si no se completó.
BTF-0018	Reproducción de idempotencia no disponible	La solicitud con esta clave `X-Idempotency` ya se completó, y su respuesta era demasiado grande para guardarla para reproducción. Lee el recurso. No reenvíes con una clave nueva, porque eso ejecuta el trabajo una segunda vez.
BTF-0107	Poller de TED IN ocupado	Otro ciclo de consulta o de reprocesamiento de TED IN ya está en curso para este tenant. Vuelve a intentarlo cuando termine.
BTF-0108	Brecha de reanudación no durable	Se rechazó la reanudación del poller. El latch de estado de recepción desconocido todavía no tiene una brecha de conciliación durable, así que el poller sigue detenido. Vuelve a intentarlo después de que se guarde la fila de la brecha.
BTF-0109	Estado incompatible con el reintento manual	La transferencia no es un `TED_OUT` detenido en `PROCESSING` y `MANUAL_REVIEW` (o en su equivalente heredado `EXHAUSTED`) con una retención preservada, o es la devolución de una TED IN. No se escribió nada, y repetir la solicitud no cambia eso.
BTF-0110	Resolución manual no permitida	Esta acción no resuelve esta transferencia, y no se resolvió nada. Vuelve a leer la transferencia.
BTF-0111	El estado del ledger contradice la resolución	El ledger contradice la resolución solicitada. Ejecuta la otra acción.
BTF-0112	Iniciación anterior al enrutamiento por ledger	La iniciación se creó antes del enrutamiento por ledger y no puede procesarse. No se escribió nada. Vuelve a iniciar la transferencia.
BTF-0113	Alcance de la transferencia no reparable	La transferencia no tiene nada que reparar, por ejemplo porque su ledger ya está definido o porque otro operador ya la reparó. Vuelve a leer la transferencia.
BTF-0114	El ledger del alcance no coincide	El CRM informa un ledger distinto para la cuenta de esta transferencia. No se escribió nada, y la respuesta no repite ninguno de los dos ledgers.
BTF-0115	Asiento no completable	El ledger tiene un asiento activo para este chargeback, y este servicio no puede completar el chargeback con él. Lee esa transacción en el ledger, liquida lo que falte fuera de esta plataforma y cierra la transferencia con `SETTLED_BY_HAND`.
BTF-0116	Reembolso cancelado	Un `RE_POST` manual registró su reembolso, y el ledger lo canceló, así que no pagó nada. Ejecuta `RE_POST` de nuevo para registrar un reembolso nuevo.
BTF-0117	Reembolso duplicado	El ledger tiene más de un reembolso activo para este chargeback. No se registró nada, y la transferencia no se cerró. No ejecutes `RE_POST` de nuevo. Lee cada transacción en `transactionIds`. Si `liveRefundSetComplete` es `false`, `transactionIds` no incluye todos los reembolsos activos: encuentra los demás en el ledger. Devuelve el excedente al beneficiario fuera de esta plataforma y luego cierra la transferencia con `SETTLED_BY_HAND`.
BTF-0119	Ya devuelta	La transferencia ya tiene una devolución activa. `transferId` nombra esa devolución.
BTF-0203	Ya procesada	Esta iniciación ya fue procesada
BTF-0216	Entrada no liquidada ya cerrada	Alguien ya registró adónde fue este dinero. Lee esa decisión antes de escribir otra.
BTF-0217	La retención se resuelve sola	Esta retención termina sola, así que no la cierres a mano. El crédito entra cuando llega su ruta en el ledger o la respuesta de titularidad. Corrige esa configuración en su lugar.
BTF-0305	Reintentos de la DLQ agotados	El mensaje de la DLQ superó el número máximo de reintentos manuales.
BTF-0307	Conflicto de rotación	Ya hay una rotación del secreto de firma en curso para este registro de webhook. Vuelve a intentar la rotación.
BTF-1094	Artefacto de firma ya usado	El artefacto de firma ya se usó.
BTF-1095	El artefacto de firma no coincide	El artefacto de firma no coincide con el payload esperado.
BTF-2002	Conflicto de estado en Midaz	Midaz informó un conflicto de estado de la transacción.
BTF-9009	Ciclo de conciliación ocupado	Ya hay un barrido de conciliación en curso. Vuelve a intentarlo después del intervalo de `Retry-After`.

410

`code`	Nombre	Descripción
BTF-0202	Iniciación expirada	La iniciación expiró después de 24 horas. Crea una nueva iniciación.
BTF-1093	Artefacto de firma expirado	El artefacto de firma expiró. El error trae `expiresAt`.

422

`code`	Nombre	Descripción
BTF-0002	Validación de dominio	El payload viola una regla de dominio, por ejemplo una URL de endpoint de webhook inválida o un tipo de evento no admitido.
BTF-0003	Campo del payload ausente	Al payload STR0008 le falta un campo obligatorio.
BTF-0004	Tipo no admitido	La operación no admite este tipo de transferencia, por ejemplo la preparación de firma en una transferencia que no es TED OUT. También rechaza un P2P que este tenant no puede hacer. `reason` indica el motivo: `cross_organization`, `cross_ledger_disabled` o `cross_ledger_flag_unreadable`. Solo `cross_ledger_flag_unreadable` puede resolverse con un reintento.
BTF-0005	Transferencia entre ledgers no disponible	Un P2P entre dos ledgers no está disponible. `reason` es `fee_mode_legacy` o `ledger_platform_below_minimum` (Midaz anterior a 4.2.0).
BTF-0006	Transferencia entre ledgers no habilitada	Un ledger del P2P no acepta asientos entre ledgers, o su ruta de operación `crossLedger` falta o no es válida. Corrige el ledger y luego inicia una nueva transferencia. En una devolución de P2P, la devolución queda en `FAILED`: corrige el ledger y luego pide la devolución de nuevo con una nueva clave `X-Idempotency`.
BTF-0007	Activos distintos entre ledgers	Las dos cuentas de un P2P entre ledgers tienen activos distintos.
BTF-0008	Etiqueta de comisión no aceptada	El `feeContext` no se acepta. Ningún paquete de comisiones en el ledger del pagador selecciona por ella, habilitado o no, o el ledger no calcula comisiones de forma nativa. No se calculó, retuvo ni escribió nada.
BTF-0010	Violación de horario de operación	La solicitud está fuera de la ventana de operación: fuera de su horario (06:30 a 17:00, hora de Brasília, de forma predeterminada), en un fin de semana o en un feriado de BACEN. La devolución de una TED IN también cierra como máximo a las 13:00 el 24 de diciembre y el último día hábil del año.
BTF-0011	Límite excedido	El monto de la transferencia supera el límite diario
BTF-0013	Violación de restricción	Los datos violan una restricción de la base de datos.
BTF-0014	Resultado de idempotencia no registrado	Una solicitud anterior con esta clave `X-Idempotency` respondió 5xx, así que la clave queda bloqueada durante la ventana de retención. Lee el recurso y, solo si el trabajo no se completó, envía la solicitud idéntica con una clave nueva.
BTF-0015	Registro de idempotencia inutilizable	Este servicio no puede leer el registro de idempotencia de esta clave. Lee el recurso y, solo si el trabajo no se completó, envía la solicitud idéntica con una clave nueva.
BTF-0017	Clave de idempotencia reutilizada	Esta clave `X-Idempotency` ya se usó en una solicitud diferente. Una repetición debe ser idéntica byte a byte, y una solicitud nueva necesita una clave nueva.
BTF-0118	No devolvible	La transferencia no puede devolverse. Solo una TED IN `COMPLETED` recibida como STR0008R2, o un P2P `COMPLETED` que no es en sí mismo una devolución, puede devolverse. No se creó nada.
BTF-0120	No reversible	El ledger no puede revertir la transacción original. `reason` es `route_not_reversible`, `original_not_approved`, `fee_account_insufficient`, `ledger_platform_below_minimum` o, en una devolución de P2P, `ledger_refused`.
BTF-0121	Retención de la devolución rechazada	El ledger rechazó reservar el monto de la devolución. `reason` es `insufficient_balance` o `prior_reservation_pending`.
BTF-0204	No se puede cancelar	La transferencia no puede cancelarse en su estado actual. Solo pueden cancelarse las transferencias CREATED o PENDING. La devolución de una TED IN no puede cancelarse.
BTF-0501	Respuesta inválida del CRM	Al registro de la cuenta en el CRM le falta un campo obligatorio (`organizationId`). Contacta a tu equipo de plataforma para corregir los datos de la cuenta en el CRM.
BTF-1001	Rechazo de JD SPB	JD SPB rechazó la transferencia. El código de JD está en `upstream.code`.
BTF-1090	Artefacto de firma requerido	Un TED OUT necesita un artefacto de firma antes de procesarse.
BTF-1096	Firma inválida	La firma digital falta o es inválida.
BTF-2003	Validación de Midaz	Midaz rechazó la solicitud de transacción.
BTF-2004	Transacción denegada por Midaz	El Tracer del ledger de Midaz denegó la transferencia por un límite o una regla, o denegó o envió a revisión la reversión de una devolución de P2P. No se registró nada.
BTF-2005	Comisión rechazada por Midaz	En el modo de comisión `native`, el Fees Engine de Midaz se negó a calcular la comisión de la transferencia. Por ejemplo, dos paquetes de comisiones coinciden con ella por igual (Midaz rechaza ese registro con el error `0198`), o una comisión descontada del monto es mayor que el monto. Este código cubre todos los errores de comisión de Midaz, de `0179` a `0233`. No se registró nada. Corrige los paquetes de comisiones y luego vuelve a iniciar la transferencia.
BTF-3002	Comisión deducible en TED OUT	El paquete de comisiones que coincide con un TED OUT, o con una TED entre cores, descuenta la comisión del monto. Ambos cobran su comisión además del monto, así que define `isDeductibleFrom: false` en las comisiones de ese paquete y vuelve a iniciar. Nada llegó a JD. Cuando el error trae `transferId`, una llamada de procesamiento anterior de esta iniciación reservó esa transferencia, y cualquier retención que haya puesto en el ledger sigue hasta que un operador la libere.
BTF-3003	Comisión deducible en el origen	El paquete de comisiones del ledger de origen de un P2P entre ledgers descuenta la comisión del monto. Define `isDeductibleFrom: false` en las comisiones de ese paquete y vuelve a iniciar.
BTF-4003	Receptor no mantenido aquí	La cuenta del receptor está en esta institución, pero ningún motor la mantiene. No se creó la transferencia. En el `/process` de una TED entre cores, el titular de la cuenta del receptor cambió después de la iniciación. No se puso ninguna retención, y la transferencia queda `FAILED`.
BTF-4004	Clave del receptor inutilizable	La sucursal y la cuenta del receptor en la solicitud no pueden convertirse en una clave del mapa de titularidad. Corrige la solicitud. Un reintento no ayuda. No se creó la transferencia.
BTF-4005	Receptor entre cores rechazó	El otro core de tu institución rechazó el crédito de una TED entre cores, o JD Courier no alcanzó a ningún destinatario. La retención se liberó, nada se movió, y la transferencia queda `REJECTED`.

Cuando JD SPB responde a un error con su propio código, el documento de problema lleva ese código sin cambios en upstream.code. Algunos ejemplos son ACE95 para tiempos de espera agotados en la solicitud, AAC90 para rechazos por firma inválida y ALN01 para respuestas de número de control no encontrado. Consulta la documentación del proveedor de JD SPB para ver la lista completa y la política de reintento correspondiente a cada código.

429

`code`	Nombre	Descripción
BTF-0429	Límite de solicitudes excedido	Demasiadas solicitudes. Reintenta después del intervalo indicado por el encabezado `Retry-After`.

Las respuestas de límite de solicitudes usan la categoría rate_limit e incluyen un encabezado Retry-After. Reduce la frecuencia de reintento según el estado HTTP 429 y ese encabezado.

500

`code`	Nombre	Descripción
BTF-9000	Error interno	Ocurrió un error inesperado. Contacta a soporte si persiste.
BTF-9002	Falla posterior al envío	La transferencia se envió, pero el registro posterior al envío falló. No vuelvas a intentarlo. El error trae `transferId` y `transferStatus`.
BTF-9006	Respuesta vacía inesperada	La capa de servicio devolvió una respuesta vacía inesperada.
BTF-9011	Transferencia varada	Cuando `/process` detuvo un TED OUT antes de que llegara a la cámara de compensación y su retención sigue activa, la conciliación toma la transferencia en un plazo de diez minutos y libera su retención cuando la cámara de compensación vuelve a abrir, así que no vuelvas a intentar `/process`. Cuando se detectó una solicitud de TED OUT duplicada después de la retención en Midaz y su reversión falló, revisa en Midaz si hay una retención no conciliada antes de volver a intentar `/process`.
BTF-9012	ISPB de origen ausente	El despliegue no tiene un ISPB de origen configurado, así que no se puede clasificar el tipo de transferencia.
BTF-9014	Ledger movido, fila no escrita	El ledger se movió, y la transferencia no llegó a su estado final. Lee la transferencia y luego envía de nuevo la solicitud idéntica con una clave `X-Idempotency` nueva. La repetición converge al estado de esta transferencia en el ledger, así que no puede mover dinero dos veces. Si la repetición no elimina el error, la transferencia necesita una inspección manual.

502

`code`	Nombre	Descripción
BTF-0501	Respuesta inválida del CRM	El CRM devolvió una respuesta ambigua o no interpretable. Contacta a tu equipo de plataforma. (BTF-0501 también aparece bajo 422 cuando al registro del CRM le falta un campo obligatorio.)
BTF-1007	Credenciales rechazadas por JD	JD SPB rechazó las credenciales. El código de JD está en `upstream.code`.
BTF-1008	Certificado rechazado por JD	JD SPB rechazó el certificado de firma o la firma digital. El código de JD está en `upstream.code`.
BTF-1009	Configuración rechazada por JD	JD SPB rechazó la configuración. El código de JD está en `upstream.code`.
BTF-3001	Respuesta inválida de Fees	El servicio de Fees devolvió una respuesta inválida o no interpretable. Contacta a tu equipo de plataforma.
BTF-4001	Respuesta inválida del mapa de titularidad	El mapa de titularidad devolvió una respuesta inutilizable. No se liquidó la transferencia.

503

`code`	Nombre	Descripción
BTF-0019	Clave de idempotencia desprotegida	El trabajo con esta clave `X-Idempotency` se ejecutó, y no se pudo guardar ni su respuesta ni el bloqueo de su resultado. La clave no protege nada, así que un reenvío puede ejecutar la operación una segunda vez. Lee el recurso antes de enviar cualquier otra cosa.
BTF-0020	Recibo de idempotencia no guardado	El trabajo con esta clave `X-Idempotency` se ejecutó y su respuesta no se pudo guardar para reproducción, pero la clave sigue reservada. Lee el recurso y reenvía con una clave nueva solo si el trabajo no se completó.
BTF-0124	Protección de la devolución no disponible	El plugin no puede garantizar ahora que la transferencia tenga como máximo una devolución activa, y no se creó nada. Cuando la causa se resuelva, pide la devolución de nuevo con una nueva clave `X-Idempotency`.
BTF-0402	Autorización no disponible	El Access Manager no respondió, así que se rechazó la solicitud. Vuelve a intentarlo más tarde.
BTF-0409	Resolución del tenant no disponible	El tenant manager o su pool de conexiones no respondió, así que no se pudo resolver la base de datos de este tenant. Vuelve a intentarlo más tarde.
BTF-0410	Tenant no aprovisionado	El tenant no tiene base de datos para este servicio. Un reintento no ayuda: hay que completar el onboarding del tenant.
BTF-0502	Servicio de CRM no disponible	No se pudo validar la cuenta. El servicio de CRM no está disponible temporalmente. Vuelve a intentarlo más tarde.
BTF-0503	Falla de autenticación en el CRM	El CRM rechazó las credenciales de Bank Transfer.
BTF-1000	JD SPB no disponible	JD SPB no está disponible.
BTF-1003	Timeout de JD SPB	JD SPB agotó el tiempo de espera.
BTF-2000	Midaz no disponible	No se pudo procesar la transferencia. El servicio del ledger de Midaz no está disponible temporalmente, o rechazó las credenciales de Midaz de Bank Transfer. Si Midaz no está disponible, vuelve a intentarlo más tarde. Una credencial rechazada no se resuelve con un reintento: comprueba sus permisos. En el modo de comisión `native`, necesita `packages` (`get`) y `estimates` (`post`). Con `MIDAZ_FEE_MODE=native` definido de forma explícita, también necesita `organizations` (`get`). En una devolución de P2P, `transferId` nombra la devolución, todavía en `CREATED`: envía la misma solicitud de nuevo con una nueva clave `X-Idempotency` para retomarla.
BTF-3000	Servicio de Fees no disponible	No se pudo calcular la comisión. El servicio de Fees no está disponible temporalmente. Vuelve a intentarlo más tarde.
BTF-4000	Mapa de titularidad no disponible	El mapa de titularidad no está disponible, y no se liquidó la transferencia. Vuelve a intentarlo más tarde. En el `/process` de una TED entre cores, también responde cuando el mapa de titularidad no muestra la cuenta del remitente como mantenida por este motor.
BTF-4002	Consulta de titularidad rechazada localmente	El plugin rechazó la consulta de titularidad localmente. No se envió nada, y no se liquidó la transferencia.
BTF-9000	Almacenamiento de idempotencia no disponible	El almacenamiento de idempotencia no estaba disponible, así que el plugin no ejecutó la solicitud. Envía la misma solicitud de nuevo con la misma clave `X-Idempotency`.
BTF-9001	Servicio de límite de uso no disponible	El servicio de límite de uso no está disponible temporalmente, así que la transferencia no puede continuar.
BTF-9003	Protección contra duplicados no disponible	El servicio de verificación de duplicados no está disponible.
BTF-9004	Subsistema de conciliación no disponible	El subsistema de conciliación no está disponible.
BTF-9005	Dependencia no configurada	Una dependencia obligatoria del servicio no está configurada.
BTF-9007	Timeout del repositorio	Una operación de base de datos agotó el tiempo de espera.
BTF-9008	Repositorio no disponible	La base de datos no está disponible.
BTF-9015	Configuración de ruta ausente	No se pudo leer una configuración de enrutamiento. El campo `systemplaneKey` indica el documento de configuración.
BTF-9016	Schema no preparado	La base de datos de este tenant no puede registrar esta escritura, y no se escribió nada. Aplica las migraciones pendientes a este tenant y luego envía de nuevo la solicitud idéntica con una clave `X-Idempotency` nueva.
BTF-9017	Alcance de organizaciones no disponible	La lista de organizaciones del tenant falta o no se puede leer. Vuelve a intentarlo con la misma clave de idempotencia cuando esté configurada.
BTF-9018	Conjunto de ISPB del tenant inválido	El tenant vincula más de un ISPB, así que no se puede decidir su identidad en la cámara de compensación. No se escribió nada.

API de Transferencias

Panel y API de Conciliación

API de Operaciones TED In

API de Webhooks

API de Webhook DLQ

Manejo de errores

Eventos

Lista de errores de Bank Transfer

Errores de Bank Transfer

202

400

401

403

404

409

410

422

429

500

502

503

​Errores de Bank Transfer

​202

​400

​401

​403

​404

​409

​410

​422

​429

​500

​502

​503

Errores de Bank Transfer

202

400

401

403

404

409

410

422

429

500

502

503