> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**

<CodeGroup>
  ```json JSON theme={null}
  {
    "error": {
      "code": "<error_code>",
      "service": "<service>",
      "category": "<category>",
      "message": "<error_message>",
      "requestId": "<request_id>",
      "fields": {}
    }
  }
  ```
</CodeGroup>

**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.

<Note>
  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`.
</Note>

## 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. |

<Note>
  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.
</Note>

### 429

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

<Note>
  Rate-limit responses use the `rate_limit` category and include a `Retry-After` header. Back off using HTTP status `429` and that header.
</Note>

### 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.             |