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

# Lista de erros do Bank Transfer

> **Bank Transfer** retorna respostas de erro consistentes e estruturadas. Isso ajuda você a entender rapidamente o que deu errado e como corrigir.

**Formato de erro**

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

**Definição dos campos**

* **`code`** – Um identificador estável e único para o erro (ex: `BTF-0010`). Rejeições do JD SPB propagam o código do fornecedor sem transformação (ex: `AAC90`); falhas em nível de transporte usam o marcador sintético `TRANSPORT`. Faça a correspondência por este valor em vez do status HTTP.
* **`service`** – O serviço ou domínio que produziu o erro (ex: `plugin`, `crm`, `midaz`, `fees`, `jd_spb`).
* **`category`** – Categoria de erro legível por máquina para decisões de retry: `deterministic`, `transient`, `rate_limit` ou `plugin`.
* **`message`** – Orientação detalhada para ajudar você a resolver o erro.
* **`requestId`** – ID de correlação da requisição. Presente mesmo quando vazio; inclua-o em solicitações de suporte.
* **`fields`** – Opcional. Metadados estruturados de validação ou retry (erros em nível de campo, detalhes de limite e similares).

Essa estrutura garante que você sempre receba feedback acionável quando algo não ocorre como esperado.

<Note>
  Nas tabelas abaixo, a coluna **title** é um rótulo legível para conveniência — não é um campo no envelope de resposta. O envelope retorna `code`, `service`, `category`, `message` e `requestId`. Faça a correspondência por `error.code`.
</Note>

## Erros do Bank Transfer

***

Os seguintes erros podem ocorrer ao interagir com os endpoints do Bank Transfer. Cada erro segue nossa estrutura padrão, facilitando a depuração e a resposta a problemas de forma programática.

Consulte as tabelas abaixo para obter uma lista dos possíveis códigos de erro, o que eles significam e como resolvê-los.

### 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>
  Os erros retornados pela integração com o JD SPB não são envelopados em códigos `BTF-*`. O código do fornecedor é propagado textualmente no campo `error.code` do envelope de erro HTTP (por exemplo, `ACE95` para timeouts de requisição, `AAC90` para rejeições por assinatura inválida, `ALN01` para respostas de número de controle não encontrado). Consulte a documentação do fornecedor JD SPB para a lista completa e a política de retry correspondente a cada código.
</Note>

### 429

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

<Note>
  As respostas de rate limit usam a categoria `rate_limit` e incluem um cabeçalho `Retry-After`. Faça backoff usando o status HTTP `429` e esse cabeçalho.
</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.             |