Lista de errores de Bank Transfer

Formato del error

{
  "error": {
    "code": "<error_code>",
    "service": "<service>",
    "category": "<category>",
    "message": "<error_message>",
    "requestId": "<request_id>",
    "fields": {}
  }
}

Definiciones de los campos

code – Un identificador estable y único para el error (por ejemplo, BTF-0010). Los rechazos de JD SPB pasan el código del proveedor sin cambios (por ejemplo, AAC90). Las fallas de transporte usan el marcador sintético TRANSPORT. Usa este valor para hacer coincidencias, no el estado HTTP.
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.
message – Orientación detallada para ayudarte a resolver el error.
requestId – ID de correlación de la solicitud. Presente incluso cuando está vacío. Inclúyelo en las solicitudes de soporte.
fields – Opcional. Metadatos estructurados de validación o reintento (errores por campo, detalles de límites y similares).

En las tablas siguientes, la columna title es una etiqueta legible para humanos, pensada para tu conveniencia. No es un campo del envelope. El envelope devuelve code, service, category, message y requestId. Usa error.code para hacer coincidencias.

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.

400

`code`	`title`	`message`
BTF-0001	Entrada inválida	La solicitud contiene campos inválidos. Revisa los detalles de los campos a continuación.

401

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

403

`code`	`title`	`message`
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.

404

`code`	`title`	`message`
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-0500	Cuenta no encontrada	La cuenta del remitente no existe en el CRM

409

`code`	`title`	`message`
BTF-0012	Transferencia duplicada	Transferencia duplicada detectada
BTF-0203	Ya procesada	Esta iniciación ya fue procesada

410

`code`	`title`	`message`
BTF-0202	Iniciación expirada	La iniciación expiró después de 24 horas. Crea una nueva iniciación.

422

`code`	`title`	`message`
BTF-0010	Violación de horario de operación	Las transferencias solo pueden iniciarse de lunes a viernes entre las 06:30 y las 17:00, hora de Brasília
BTF-0011	Límite excedido	El monto de la transferencia supera el límite diario
BTF-0204	No se puede cancelar	La transferencia no puede cancelarse en su estado actual. Solo pueden cancelarse las transferencias CREATED o PENDING.
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.

Los errores de la integración con JD SPB no usan códigos BTF-*. El código del proveedor se pasa tal cual en el campo error.code del envelope de error HTTP (por ejemplo, ACE95 para tiempos de espera agotados en la solicitud, AAC90 para rechazos por firma inválida, 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`	`title`	`message`
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`	`title`	`message`
BTF-9000	Error interno	Ocurrió un error inesperado. Contacta a soporte si persiste.

502

`code`	`title`	`message`
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-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.)

503

`code`	`title`	`message`
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-2000	Midaz no disponible	No se pudo procesar la transferencia. El servicio del ledger de Midaz no está disponible temporalmente. Vuelve a intentarlo más tarde.
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.

API de Transferencias

Panel y API de Conciliación

API de Operaciones TED In

API de Webhooks

API de Webhook DLQ

Manejo de errores

Lista de errores de Bank Transfer

Errores de Bank Transfer

400

401

403

404

409

410

422

429

500

502

503

​Errores de Bank Transfer

​400

​401

​403

​404

​409

​410

​422

​429

​500

​502

​503

Errores de Bank Transfer

400

401

403

404

409

410

422

429

500

502

503