> ## 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
> O **Bank Transfer** retorna respostas de erro estruturadas, para que você identifique o que deu errado e como corrigir.
**Formato do erro**
```json JSON theme={null}
{
"error": {
"code": "",
"service": "",
"category": "",
"message": "",
"requestId": "",
"fields": {}
}
}
```
**Definições de campo**
* **`code`** – Um identificador estável e único do erro (por exemplo, `BTF-0010`). As rejeições do JD SPB repassam o código bruto do fornecedor (por exemplo, `AAC90`). Falhas no nível de transporte usam o marcador sintético `TRANSPORT`. Use esse valor para comparação, não o status HTTP.
* **`service`** – O serviço ou domínio que produziu o erro (por exemplo, `plugin`, `crm`, `midaz`, `fees`, `jd_spb`).
* **`category`** – Categoria de erro legível por máquina para decisões de nova tentativa: `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 nas solicitações de suporte.
* **`fields`** – Opcional. Metadados estruturados de validação ou nova tentativa (erros por campo, detalhes de limite e outros).
Nas tabelas abaixo, a coluna **title** é um rótulo legível para facilitar a leitura. Não é um campo do envelope de resposta. O envelope retorna `code`, `service`, `category`, `message` e `requestId`. Use `error.code` para comparação.
## Erros do Bank Transfer
***
Os erros a seguir podem ocorrer ao interagir com os endpoints do Bank Transfer. Cada erro segue a nossa estrutura padrão.
Consulte as tabelas abaixo para ver a lista de códigos de erro possíveis, o que eles significam e como resolvê-los.
### 400
| `code` | `title` | `message` |
| -------- | ---------------- | ------------------------------------------------------------------------------ |
| BTF-0001 | Entrada inválida | A requisição contém campos inválidos. Verifique os detalhes dos campos abaixo. |
### 401
| `code` | `title` | `message` |
| -------- | -------------- | ------------------------------------------------------------------ |
| BTF-0401 | Não autorizado | Falha na autenticação. O token está ausente, inválido ou expirado. |
### 403
| `code` | `title` | `message` |
| -------- | ---------------- | ---------------------------------------------------------------------------------------- |
| BTF-0403 | Licença inválida | A organização não tem licença. Entre em contato com o suporte para ativar a sua licença. |
| BTF-0405 | Proibido | Permissões insuficientes para executar esta ação. |
### 404
| `code` | `title` | `message` |
| -------- | ---------------------------- | -------------------------------------------------------- |
| BTF-0200 | Transferência não encontrada | Transferência não encontrada |
| BTF-0201 | Iniciação não encontrada | Iniciação não encontrada ou pertence a outra organização |
| BTF-0500 | Conta não encontrada | A conta do remetente não existe no CRM |
### 409
| `code` | `title` | `message` |
| -------- | ----------------------- | --------------------------------- |
| BTF-0012 | Transferência duplicada | Transferência duplicada detectada |
| BTF-0203 | Já processada | Esta iniciação já foi processada |
### 410
| `code` | `title` | `message` |
| -------- | ------------------ | ----------------------------------------------------------- |
| BTF-0202 | Iniciação expirada | A iniciação expirou após 24 horas. Crie uma nova iniciação. |
### 422
| `code` | `title` | `message` |
| -------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BTF-0010 | Violação do horário de funcionamento | As transferências apenas podem ser iniciadas de segunda a sexta-feira, entre 06:30 e 17:00, horário de Brasília |
| BTF-0011 | Limite excedido | O valor da transferência excede o limite diário |
| BTF-0204 | Não é possível cancelar | A transferência não pode ser cancelada no status atual. Apenas transferências CREATED ou PENDING podem ser canceladas. |
| BTF-0501 | Resposta inválida do CRM | O registro da conta no CRM não tem um campo obrigatório (`organizationId`). Entre em contato com a sua equipe de plataforma para corrigir os dados da conta no CRM. |
Os erros da integração JD SPB não usam códigos `BTF-*`. O código do fornecedor é repassado literalmente no campo `error.code` do envelope de erro HTTP (por exemplo, `ACE95` para tempos limite de requisição, `AAC90` para rejeições de 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 nova tentativa correspondente a cada código.
### 429
| `code` | `title` | `message` |
| -------- | ------------------------------ | ---------------------------------------------------------------------------------------- |
| BTF-0429 | Limite de requisições excedido | Muitas requisições. Tente novamente após o intervalo indicado pelo header `Retry-After`. |
As respostas de limite de requisições usam a categoria `rate_limit` e incluem um header `Retry-After`. Aplique backoff usando o status HTTP `429` e esse header.
### 500
| `code` | `title` | `message` |
| -------- | ------------ | ------------------------------------------------------------------------ |
| BTF-9000 | Erro interno | Ocorreu um erro inesperado. Entre em contato com o suporte se persistir. |
### 502
| `code` | `title` | `message` |
| -------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BTF-3001 | Resposta inválida do Fees | O serviço de tarifas retornou uma resposta inválida ou que não pôde ser interpretada. Entre em contato com a sua equipe de plataforma. |
| BTF-0501 | Resposta inválida do CRM | O CRM retornou uma resposta ambígua ou que não pôde ser interpretada. Entre em contato com a sua equipe de plataforma. (O BTF-0501 também aparece em 422 quando falta um campo obrigatório no registro do CRM.) |
### 503
| `code` | `title` | `message` |
| -------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| BTF-0502 | Serviço do CRM indisponível | Não foi possível validar a conta. O serviço do CRM está temporariamente indisponível. Tente novamente mais tarde. |
| BTF-2000 | Midaz indisponível | Não foi possível processar a transferência. O serviço de ledger do Midaz está temporariamente indisponível. Tente novamente mais tarde. |
| BTF-3000 | Serviço de tarifas indisponível | Não foi possível calcular a tarifa. O serviço de tarifas está temporariamente indisponível. Tente novamente mais tarde. |