Bank Transfer error list

Bank Transfer returns consistent and structured error responses. This helps you quickly understand what went wrong and how to fix it.

Error format

JSON

{
  "error": {
    "code": "<error_code>",
    "message": "<error_message>"
  }
}

Field definitions

• code – A stable, unique identifier for the error. Useful for programmatic handling and support requests.
• message – Detailed guidance to help you resolve the error.

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

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.

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.

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.