Lista de errores de Bank Transfer

Formato de error

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

Definición de campos

code – Un identificador estable y único para el error (p. ej. BTF-0010). Los rechazos de JD SPB propagan el código bruto del proveedor (p. ej. AAC90); los fallos a nivel de transporte usan el marcador sintético TRANSPORT. Haz coincidencia sobre este valor en lugar del estado HTTP.
service – El servicio o dominio que produjo el error (p. ej. 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 a nivel de campo, detalles de límites y similares).

Esta estructura garantiza que siempre recibas retroalimentación accionable cuando algo no sale como esperado.

En las tablas a continuación, la columna title es una etiqueta legible por humanos por conveniencia — no es un campo en el envoltorio de la respuesta. El envoltorio devuelve code, service, category, message y requestId. Haz coincidencia sobre error.code.

Errores de Bank Transfer

Los siguientes errores pueden ocurrir al interactuar con los endpoints de Bank Transfer. Cada error sigue nuestra estructura estándar, facilitando la depuración y la respuesta a problemas de forma programática. Consulta las tablas a continuación para obtener una lista de los posibles códigos de error, su significado y cómo resolverlos.

400

`code`	`title`	`message`
BTF-0001	Invalid Input	The request contains invalid fields. Check the field details below.

401

`code`	`title`	`message`
BTF-0401	Unauthorized	Authentication failed. The token is missing, invalid, or expired.

403

`code`	`title`	`message`
BTF-0403	License Invalid	Organization is not licensed. Contact support to activate your license.
BTF-0405	Forbidden	Insufficient permissions to perform this action.

404

`code`	`title`	`message`
BTF-0200	Transfer Not Found	Transfer not found
BTF-0201	Initiation Not Found	Initiation not found or belongs to different organization
BTF-0500	Account Not Found	Sender account does not exist in CRM

409

`code`	`title`	`message`
BTF-0012	Duplicate Transfer	Duplicate transfer detected
BTF-0203	Already Processed	This initiation has already been processed

410

`code`	`title`	`message`
BTF-0202	Initiation Expired	Initiation expired after 24 hours. Create a new initiation.

422

`code`	`title`	`message`
BTF-0010	Operating Hours Violation	Transfers can only be initiated Monday-Friday between 06:30 and 17:00 Brasília time
BTF-0011	Limit Exceeded	Transfer amount exceeds daily limit
BTF-0204	Cannot Cancel	Transfer cannot be cancelled in its current status. Only CREATED or PENDING transfers can be cancelled.
BTF-0501	CRM Invalid Response	The CRM account record is missing a required field (`organizationId`). Contact your platform team to fix the account data in the CRM.

Los errores devueltos por la integración con JD SPB no se encapsulan en códigos BTF-*. El código del proveedor se propaga textualmente en el campo error.code del envoltorio de error HTTP (por ejemplo, ACE95 para timeouts de solicitud, AAC90 para rechazos por firma inválida, ALN01 para respuestas de número de control no encontrado). Consulta la documentación del proveedor JD SPB para la lista completa y la política de reintento correspondiente a cada código.

429

`code`	`title`	`message`
BTF-0429	Rate Limited	Too many requests. Retry after the interval indicated by the `Retry-After` header.

Las respuestas de rate-limit usan la categoría rate_limit e incluyen un header Retry-After. Haz back off usando el estado HTTP 429 y ese header.

500

`code`	`title`	`message`
BTF-9000	Internal Error	An unexpected error occurred. Contact support if it persists.

502

`code`	`title`	`message`
BTF-3001	Fees Invalid Response	The fee service returned an invalid or unparseable response. Contact your platform team.
BTF-0501	CRM Invalid Response	The CRM returned an ambiguous or unparseable response. Contact your platform team. (BTF-0501 also appears under 422 when the CRM record is missing a required field.)

503

`code`	`title`	`message`
BTF-0502	CRM Service Unavailable	Unable to validate account. The CRM service is temporarily unavailable. Try again later.
BTF-2000	Midaz Unavailable	Unable to process transfer. The Midaz ledger service is temporarily unavailable. Try again later.
BTF-3000	Fee Service Unavailable	Unable to calculate fee. The fee service is temporarily unavailable. Try again later.

​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