Bank Transfer error list

Error format

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

Field definitions

code – A stable, unique identifier for the error (e.g. BTF-0010). JD SPB rejections pass through the raw vendor code (e.g. AAC90); transport-level failures use the synthetic marker TRANSPORT. Match on this value rather than on the HTTP status.
service – The service or domain that produced the error (e.g. plugin, crm, midaz, fees, jd_spb).
category – Machine-readable error category for retry decisions: deterministic, transient, rate_limit, or plugin.
message – Detailed guidance to help you resolve the error.
requestId – Correlation ID for the request. Present even when empty; include it in support requests.
fields – Optional. Structured validation or retry metadata (field-level errors, limit details, and similar).

This structure ensures you always get actionable feedback when something doesn’t go as expected.

In the tables below, the title column is a human-readable label for convenience — it is not a field in the response envelope. The envelope returns code, service, category, message, and requestId. Match on error.code.

Bank Transfer errors

The following errors can occur when interacting with the Bank Transfer endpoints. Each error follows our standard structure, making it easier to debug and respond to issues programmatically. Refer to the tables below for a list of possible error codes, what they mean, and how to resolve them.

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.

Errors returned by the JD SPB integration are not wrapped in BTF-* codes. The vendor code is passed through verbatim on the error.code field of the HTTP error envelope (for example, ACE95 for request timeouts, AAC90 for invalid signature rejections, ALN01 for control-number-not-found responses). Refer to the JD SPB vendor documentation for the full list and the corresponding retry policy for each code.

429

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

Rate-limit responses use the rate_limit category and include a Retry-After header. Back off using HTTP status 429 and that 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.

​Bank Transfer errors

​400

​401

​403

​404

​409

​410

​422

​429

​500

​502

​503

Bank Transfer errors

400

401

403

404

409

410

422

429

500

502

503