> ## 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 errores de Bank Transfer

> Bank Transfer devuelve respuestas de error consistentes y estructuradas. Esto te ayuda a entender rápidamente qué salió mal y cómo solucionarlo.

**Formato de error**

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

**Definición de campos**

* **`code`** – Un identificador estable y único para el error (p. ej. `BTF-0010`). Los rechazos de JD SPB propagan el código bruto del proveedor (p. ej. `AAC90`); los fallos a nivel de transporte usan el marcador sintético `TRANSPORT`. Haz coincidencia sobre este valor en lugar del estado HTTP.
* **`service`** – El servicio o dominio que produjo el error (p. ej. `plugin`, `crm`, `midaz`, `fees`, `jd_spb`).
* **`category`** – Categoría de error legible por máquina para decisiones de reintento: `deterministic`, `transient`, `rate_limit` o `plugin`.
* **`message`** – Orientación detallada para ayudarte a resolver el error.
* **`requestId`** – ID de correlación de la solicitud. Presente incluso cuando está vacío; inclúyelo en las solicitudes de soporte.
* **`fields`** – Opcional. Metadatos estructurados de validación o reintento (errores a nivel de campo, detalles de límites y similares).

Esta estructura garantiza que siempre recibas retroalimentación accionable cuando algo no sale como esperado.

<Note>
  En las tablas a continuación, la columna **title** es una etiqueta legible por humanos por conveniencia — no es un campo en el envoltorio de la respuesta. El envoltorio devuelve `code`, `service`, `category`, `message` y `requestId`. Haz coincidencia sobre `error.code`.
</Note>

## Errores de Bank Transfer

***

Los siguientes errores pueden ocurrir al interactuar con los endpoints de Bank Transfer. Cada error sigue nuestra estructura estándar, facilitando la depuración y la respuesta a problemas de forma programática.

Consulta las tablas a continuación para obtener una lista de los posibles códigos de error, su significado y cómo resolverlos.

### 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>
  Los errores devueltos por la integración con JD SPB no se encapsulan en códigos `BTF-*`. El código del proveedor se propaga textualmente en el campo `error.code` del envoltorio de error HTTP (por ejemplo, `ACE95` para timeouts de solicitud, `AAC90` para rechazos por firma inválida, `ALN01` para respuestas de número de control no encontrado). Consulta la documentación del proveedor JD SPB para la lista completa y la política de reintento correspondiente 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>
  Las respuestas de rate-limit usan la categoría `rate_limit` e incluyen un header `Retry-After`. Haz back off usando el estado HTTP `429` y ese 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.             |