> ## 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 structured error responses, so you can identify 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).

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

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 from the JD SPB integration do not use `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.             |