Lista de erros do Bank Transfer

Formato do erro

{
  "error": {
    "code": "<error_code>",
    "service": "<service>",
    "category": "<category>",
    "message": "<error_message>",
    "requestId": "<request_id>",
    "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.

API de Transferências

Painel e API de Conciliação

API de Operações TED In

API de Webhooks

API de Webhook DLQ

Tratamento de erros

Lista de erros do Bank Transfer

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

Erros do Bank Transfer

400

401

403

404

409

410

422

429

500

502

503