Lista de erros do Bank Transfer

Formato de erro

{
  "error": {
    "code": "<error_code>",
    "service": "<service>",
    "category": "<category>",
    "message": "<error_message>",
    "requestId": "<request_id>",
    "fields": {}
  }
}

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.

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.

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.

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.

429

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

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.

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.

​Erros do Bank Transfer

​400

​401

​403

​404

​409

​410

​422

​429

​500

​502

​503

Erros do Bank Transfer

400

401

403

404

409

410

422

429

500

502

503