Lista de erros do Bank Transfer

Formato do erro

{
  "type": "https://errors.lerian.studio/v1/BTF-0203",
  "title": "Conflict",
  "status": 409,
  "detail": "this initiation has already been processed",
  "code": "BTF-0203",
  "category": "deterministic",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin",
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d"
}

Definições de campo

type – Uma URI que identifica o código do erro: https://errors.lerian.studio/v1/<code>.
title – O texto do status HTTP.
status – O código de status HTTP.
detail – Uma explicação legível deste erro.
code – Um identificador estável do erro (por exemplo, BTF-0010).
requestId – ID de correlação da requisição. Presente mesmo quando vazio. Inclua-o nas solicitações de suporte.
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.
errors – Opcional. Uma entrada para cada campo rejeitado, com message e location (body.<field> ou query.<field>).
upstream – Opcional. O código de erro que um provedor externo, como o JD SPB, retornou. Ele fica em upstream.code, literalmente.

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.

202

`code`	Nome	Descrição
BTF-9010	Transferência escalada para a conciliação	O avanço do TED OUT falhou, e o plugin escalou a transferência para a conciliação. A retenção no Midaz continua intacta. Consulte `GET /v1/transfers/{transferId}` até obter o status final. O corpo é um documento de problema, não uma resposta de transferência.

400

`code`	Nome	Descrição
BTF-0001	Entrada inválida	A requisição contém campos inválidos. Verifique os detalhes dos campos abaixo.
BTF-0210	Motivo de retenção inválido	O filtro de motivo de retenção está fora do vocabulário declarado.
BTF-0214	Estado de retenção inválido	O filtro `state` não é `open`, `closed` nem `all`.

401

`code`	Nome	Descrição
BTF-0401	Não autorizado	Falha na autenticação. O token está ausente, inválido ou expirado.

403

`code`	Nome	Descrição
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.
BTF-0406	Identidade de operador obrigatória	O token não identifica uma pessoa (uma conta de serviço ou um token de outro tipo), então o plugin não consegue atribuir esta escrita manual a um operador. Nenhuma permissão resolve isso. Chame o endpoint com um token de usuário.
BTF-0408	Tenant suspenso	O tenant manager recusou o acesso deste tenant ao serviço.

404

`code`	Nome	Descrição
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-0215	Entrada não liquidada não encontrada	A mensagem não tem nada que um operador possa fechar. Uma mensagem que não existe retorna o mesmo código.
BTF-0306	Webhook não encontrado	O registro de webhook não existe ou pertence a outro tenant.
BTF-0404	Organização fora do tenant	`X-Organization-Id` indica uma organização que este tenant não opera.
BTF-0407	Tenant não encontrado	O tenant manager não conhece o tenant que o token indica.
BTF-0500	Conta não encontrada	A conta do remetente não existe no CRM
BTF-1092	Artefato de assinatura não encontrado	O artefato de assinatura não foi encontrado.
BTF-2001	Conta do Midaz não encontrada	A conta do Midaz não foi encontrada.

409

`code`	Nome	Descrição
BTF-0012	Transferência duplicada	Transferência duplicada detectada
BTF-0016	Requisição de idempotência em andamento	Uma requisição com esta chave `X-Idempotency` ainda mantém a chave reservada. Enquanto a primeira requisição ainda roda, reenvie a requisição idêntica depois do intervalo de `Retry-After`. Se uma requisição anterior com esta chave respondeu 5xx, nenhuma resposta vem dela: leia o recurso e envie o trabalho com uma nova chave apenas se ele não foi efetivado.
BTF-0018	Reprodução de idempotência indisponível	A requisição com esta chave `X-Idempotency` já foi concluída, e a resposta dela era grande demais para ser armazenada para reprodução. Leia o recurso. Não reenvie com uma nova chave, porque isso executa o trabalho uma segunda vez.
BTF-0107	Poller de TED IN ocupado	Outro ciclo de consulta ou de reprocessamento de TED IN já está em andamento para este tenant. Tente novamente quando ele terminar.
BTF-0108	Lacuna de retomada não durável	A retomada do poller foi recusada. O latch de estado de recebimento desconhecido ainda não tem uma lacuna de conciliação durável, então o poller continua parado. Tente novamente depois que a linha da lacuna for gravada.
BTF-0109	Estado incompatível com a nova tentativa manual	A transferência não é um `TED_OUT` parado em `PROCESSING` e `MANUAL_REVIEW` (ou no equivalente legado `EXHAUSTED`) com uma retenção preservada, ou é a devolução de um TED IN. Nada foi gravado, e repetir a requisição não muda isso.
BTF-0110	Resolução manual não permitida	Esta ação não resolve esta transferência, e nada foi resolvido. Leia a transferência de novo.
BTF-0111	Estado do ledger contradiz a resolução	O ledger contradiz a resolução pedida. Execute a outra ação.
BTF-0112	Iniciação anterior ao roteamento por ledger	A iniciação foi criada antes do roteamento por ledger e não pode ser processada. Nada foi gravado. Inicie a transferência de novo.
BTF-0113	Escopo da transferência não reparável	A transferência não tem nada a reparar, por exemplo porque o ledger dela já está definido ou porque outro operador já a reparou. Leia a transferência de novo.
BTF-0114	Ledger do escopo divergente	O CRM informa um ledger diferente para a conta desta transferência. Nada foi gravado, e a resposta não repete nenhum dos dois ledgers.
BTF-0115	Lançamento não concluível	O ledger tem um lançamento ativo para este chargeback, e este serviço não consegue concluir o chargeback com ele. Leia essa transação no ledger, liquide o que falta fora desta plataforma e feche a transferência com `SETTLED_BY_HAND`.
BTF-0116	Reembolso cancelado	Um `RE_POST` manual registrou o reembolso, e o ledger o cancelou, então ele não pagou nada. Execute `RE_POST` de novo para registrar um novo reembolso.
BTF-0117	Reembolso em duplicidade	O ledger tem mais de um reembolso ativo para este chargeback. Nada foi lançado, e a transferência não foi fechada. Não execute `RE_POST` de novo. Leia cada transação em `transactionIds`. Se `liveRefundSetComplete` for `false`, `transactionIds` não lista todos os reembolsos ativos: encontre os outros no ledger. Devolva o excedente ao beneficiário fora desta plataforma e depois feche a transferência com `SETTLED_BY_HAND`.
BTF-0119	Já devolvida	A transferência já tem uma devolução ativa. `transferId` nomeia essa devolução.
BTF-0203	Já processada	Esta iniciação já foi processada
BTF-0216	Entrada não liquidada já fechada	Alguém já registrou para onde este dinheiro foi. Leia essa decisão antes de gravar outra.
BTF-0217	Retenção se resolve sozinha	Esta retenção termina sozinha, então não a feche manualmente. O crédito entra assim que a rota no ledger ou a resposta de titularidade chegar. Corrija essa configuração em vez disso.
BTF-0305	Tentativas da DLQ esgotadas	A mensagem da DLQ excedeu o número máximo de novas tentativas manuais.
BTF-0307	Conflito de rotação	Uma rotação do segredo de assinatura já está em andamento para este registro de webhook. Tente a rotação de novo.
BTF-1094	Artefato de assinatura já usado	O artefato de assinatura já foi usado.
BTF-1095	Artefato de assinatura divergente	O artefato de assinatura não corresponde ao payload esperado.
BTF-2002	Conflito de estado no Midaz	O Midaz informou um conflito de estado da transação.
BTF-9009	Ciclo de conciliação ocupado	Uma varredura de conciliação já está em andamento. Tente novamente depois do intervalo de `Retry-After`.

410

`code`	Nome	Descrição
BTF-0202	Iniciação expirada	A iniciação expirou após 24 horas. Crie uma nova iniciação.
BTF-1093	Artefato de assinatura expirado	O artefato de assinatura expirou. O erro traz `expiresAt`.

422

`code`	Nome	Descrição
BTF-0002	Validação de domínio	O payload viola uma regra de domínio, por exemplo uma URL de endpoint de webhook inválida ou um tipo de evento não suportado.
BTF-0003	Campo do payload ausente	Falta um campo obrigatório no payload STR0008.
BTF-0004	Tipo não suportado	A operação não suporta este tipo de transferência, por exemplo a preparação de assinatura em uma transferência que não é TED OUT. Também recusa um P2P que este tenant não pode fazer. `reason` diz o motivo: `cross_organization`, `cross_ledger_disabled` ou `cross_ledger_flag_unreadable`. Apenas `cross_ledger_flag_unreadable` pode ser resolvido com uma nova tentativa.
BTF-0005	Transferência entre ledgers indisponível	Um P2P entre dois ledgers não está disponível. `reason` é `fee_mode_legacy` ou `ledger_platform_below_minimum` (Midaz anterior à 4.2.0).
BTF-0006	Transferência entre ledgers não habilitada	Um ledger do P2P não aceita lançamentos entre ledgers, ou a rota de operação `crossLedger` dele está ausente ou é inválida. Corrija o ledger e depois inicie uma nova transferência. Em uma devolução de P2P, a devolução fica `FAILED`: corrija o ledger e depois peça a devolução de novo com uma nova chave `X-Idempotency`.
BTF-0007	Ativos diferentes entre ledgers	As duas contas de um P2P entre ledgers têm ativos diferentes.
BTF-0008	Rótulo de tarifa não aceito	O `feeContext` não é aceito. Nenhum pacote de tarifas no ledger do pagador seleciona por ele, habilitado ou não, ou o ledger não calcula tarifas de forma nativa. Nada foi calculado, retido nem gravado.
BTF-0010	Violação do horário de funcionamento	A requisição está fora da janela de funcionamento: fora do horário (06:30 a 17:00, horário de Brasília, por padrão), em um fim de semana ou em um feriado do BACEN. A devolução de um TED IN também fecha no máximo às 13:00 em 24 de dezembro e no último dia útil do ano.
BTF-0011	Limite excedido	O valor da transferência excede o limite diário
BTF-0013	Violação de restrição	Os dados violam uma restrição do banco de dados.
BTF-0014	Resultado de idempotência não registrado	Uma requisição anterior com esta chave `X-Idempotency` respondeu 5xx, então a chave fica bloqueada durante a janela de retenção. Leia o recurso e, apenas se o trabalho não foi efetivado, envie a requisição idêntica com uma nova chave.
BTF-0015	Registro de idempotência inutilizável	Este serviço não consegue ler o registro de idempotência desta chave. Leia o recurso e, apenas se o trabalho não foi efetivado, envie a requisição idêntica com uma nova chave.
BTF-0017	Chave de idempotência reutilizada	Esta chave `X-Idempotency` já foi usada em uma requisição diferente. Uma repetição precisa ser idêntica byte a byte, e uma nova requisição precisa de uma nova chave.
BTF-0118	Não devolvível	A transferência não pode ser devolvida. Apenas um TED IN `COMPLETED` recebido como STR0008R2, ou um P2P `COMPLETED` que não é ele mesmo uma devolução, pode ser devolvido. Nada foi criado.
BTF-0120	Não estornável	O ledger não consegue estornar a transação original. `reason` é `route_not_reversible`, `original_not_approved`, `fee_account_insufficient`, `ledger_platform_below_minimum` ou, em uma devolução de P2P, `ledger_refused`.
BTF-0121	Retenção da devolução recusada	O ledger recusou reservar o valor da devolução. `reason` é `insufficient_balance` ou `prior_reservation_pending`.
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. A devolução de um TED IN não pode ser cancelada.
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.
BTF-1001	Rejeitado pelo JD SPB	O JD SPB rejeitou a transferência. O código da JD está em `upstream.code`.
BTF-1090	Artefato de assinatura obrigatório	Um TED OUT precisa de um artefato de assinatura antes de ser processado.
BTF-1096	Assinatura inválida	A assinatura digital está ausente ou é inválida.
BTF-2003	Validação do Midaz	O Midaz recusou a requisição de transação.
BTF-2004	Transação negada pelo Midaz	O Tracer do ledger do Midaz negou a transferência por um limite ou uma regra, ou negou ou enviou para revisão o estorno de uma devolução de P2P. Nada foi lançado.
BTF-2005	Tarifa recusada pelo Midaz	No modo de tarifa `native`, o Fees Engine do Midaz se recusou a calcular a tarifa da transferência. Por exemplo, dois pacotes de tarifas correspondem a ela igualmente (o Midaz recusa esse lançamento com o erro `0198`), ou uma tarifa descontada do valor é maior que o valor. Este código cobre todos os erros de tarifa do Midaz, de `0179` a `0233`. Nada foi lançado. Corrija os pacotes de tarifas e depois inicie a transferência de novo.
BTF-3002	Tarifa dedutível no TED OUT	O pacote de tarifas que corresponde a um TED OUT, ou a um TED entre cores, desconta a tarifa do valor. Os dois cobram a tarifa por cima do valor, então defina `isDeductibleFrom: false` nas tarifas desse pacote e inicie de novo. Nada chegou à JD. Quando o erro traz `transferId`, uma chamada de processamento anterior desta iniciação reservou essa transferência, e qualquer retenção que ela colocou no ledger fica até um operador liberá-la.
BTF-3003	Tarifa dedutível na origem	O pacote de tarifas do ledger de origem de um P2P entre ledgers desconta a tarifa do valor. Defina `isDeductibleFrom: false` nas tarifas desse pacote e inicie de novo.
BTF-4003	Recebedor não mantido aqui	A conta do recebedor está nesta instituição, mas nenhum motor a mantém. A transferência não foi criada. No `/process` de um TED entre cores, o detentor da conta do recebedor mudou depois da iniciação. Nenhuma retenção foi colocada, e a transferência fica `FAILED`.
BTF-4004	Chave do recebedor inutilizável	A agência e a conta do recebedor na requisição não podem virar uma chave do mapa de titularidade. Corrija a requisição. Uma nova tentativa não ajuda. A transferência não foi criada.
BTF-4005	Recebedor entre cores recusou	O outro core da sua instituição recusou o crédito de um TED entre cores, ou o JD Courier não alcançou nenhum destinatário. A retenção foi liberada, nada se moveu, e a transferência fica `REJECTED`.

Quando o JD SPB responde a um erro com o próprio código, o documento de problema traz esse código literalmente em upstream.code. Exemplos são ACE95 para tempos limite de requisição, AAC90 para rejeições de assinatura inválida e 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`	Nome	Descrição
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`	Nome	Descrição
BTF-9000	Erro interno	Ocorreu um erro inesperado. Entre em contato com o suporte se persistir.
BTF-9002	Falha após o envio	A transferência foi enviada, mas o registro posterior ao envio falhou. Não tente novamente. O erro traz `transferId` e `transferStatus`.
BTF-9006	Resposta vazia inesperada	A camada de serviço retornou uma resposta vazia inesperada.
BTF-9011	Transferência travada	Quando `/process` parou um TED OUT antes de ele chegar à câmara de compensação e a retenção dele continua ativa, a conciliação pega a transferência em até dez minutos e libera a retenção quando a câmara de compensação abrir de novo, então não tente `/process` de novo. Quando uma requisição de TED OUT duplicada foi detectada depois da retenção no Midaz e a reversão dela falhou, verifique no Midaz se há uma retenção não conciliada antes de tentar `/process` de novo.
BTF-9012	ISPB de origem ausente	O deploy não tem um ISPB de origem configurado, então o tipo de transferência não pode ser classificado.
BTF-9014	Ledger movido, linha não gravada	O ledger se moveu, e a transferência não chegou ao estado final. Leia a transferência e depois envie a requisição idêntica de novo com uma nova chave `X-Idempotency`. A repetição converge para o estado desta transferência no ledger, então não movimenta dinheiro duas vezes. Se a repetição não eliminar o erro, a transferência precisa de inspeção manual.

502

`code`	Nome	Descrição
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.)
BTF-1007	Credenciais recusadas pela JD	O JD SPB recusou as credenciais. O código da JD está em `upstream.code`.
BTF-1008	Certificado recusado pela JD	O JD SPB recusou o certificado de assinatura ou a assinatura digital. O código da JD está em `upstream.code`.
BTF-1009	Configuração recusada pela JD	O JD SPB recusou a configuração. O código da JD está em `upstream.code`.
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-4001	Resposta inválida do mapa de titularidade	O mapa de titularidade retornou uma resposta inutilizável. A transferência não foi liquidada.

503

`code`	Nome	Descrição
BTF-0019	Chave de idempotência desprotegida	O trabalho com esta chave `X-Idempotency` foi executado, e nem a resposta nem o bloqueio do resultado puderam ser armazenados. A chave não protege nada, então um reenvio pode executar a operação uma segunda vez. Leia o recurso antes de enviar qualquer outra coisa.
BTF-0020	Recibo de idempotência não armazenado	O trabalho com esta chave `X-Idempotency` foi executado e a resposta não pôde ser armazenada para reprodução, mas a chave continua reservada. Leia o recurso e reenvie com uma nova chave apenas se o trabalho não foi efetivado.
BTF-0124	Proteção da devolução indisponível	O plugin não consegue garantir agora que a transferência tenha no máximo uma devolução ativa, e nada foi criado. Quando a causa for resolvida, peça a devolução de novo com uma nova chave `X-Idempotency`.
BTF-0402	Autorização indisponível	O Access Manager não respondeu, então a requisição foi recusada. Tente novamente mais tarde.
BTF-0409	Resolução do tenant indisponível	O tenant manager ou o pool de conexões dele não respondeu, então o banco de dados deste tenant não pôde ser resolvido. Tente novamente mais tarde.
BTF-0410	Tenant não provisionado	O tenant não tem banco de dados para este serviço. Uma nova tentativa não ajuda: o onboarding do tenant precisa ser concluído.
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-0503	Falha de autenticação no CRM	O CRM recusou as credenciais do Bank Transfer.
BTF-1000	JD SPB indisponível	O JD SPB está indisponível.
BTF-1003	Timeout do JD SPB	O JD SPB excedeu o tempo limite.
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, ou recusou as credenciais do Midaz do Bank Transfer. Se o Midaz está indisponível, tente novamente mais tarde. Uma credencial recusada não se resolve com uma nova tentativa: verifique as permissões dela. No modo de tarifa `native`, ela precisa de `packages` (`get`) e `estimates` (`post`). Com `MIDAZ_FEE_MODE=native` definido explicitamente, ela também precisa de `organizations` (`get`). Em uma devolução de P2P, `transferId` nomeia a devolução, ainda `CREATED`: envie a mesma requisição de novo com uma nova chave `X-Idempotency` para retomá-la.
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.
BTF-4000	Mapa de titularidade indisponível	O mapa de titularidade está indisponível, e a transferência não foi liquidada. Tente novamente mais tarde. No `/process` de um TED entre cores, ele também responde quando o mapa de titularidade não mostra a conta do remetente como mantida por este motor.
BTF-4002	Consulta de titularidade recusada localmente	O plugin recusou a consulta de titularidade localmente. Nada foi enviado, e a transferência não foi liquidada.
BTF-9000	Armazenamento de idempotência indisponível	O armazenamento de idempotência não estava disponível, então o plugin não executou a requisição. Envie a mesma requisição novamente com a mesma chave `X-Idempotency`.
BTF-9001	Serviço de limite de uso indisponível	O serviço de limite de uso está temporariamente indisponível, então a transferência não pode prosseguir.
BTF-9003	Proteção contra duplicidade indisponível	O serviço de verificação de duplicidade está indisponível.
BTF-9004	Subsistema de conciliação indisponível	O subsistema de conciliação está indisponível.
BTF-9005	Dependência não configurada	Uma dependência obrigatória do serviço não está configurada.
BTF-9007	Timeout do repositório	Uma operação de banco de dados excedeu o tempo limite.
BTF-9008	Repositório indisponível	O banco de dados está indisponível.
BTF-9015	Configuração de rota ausente	Uma configuração de roteamento não pôde ser lida. O campo `systemplaneKey` indica o documento de configuração.
BTF-9016	Schema não preparado	O banco de dados deste tenant não consegue registrar esta escrita, e nada foi gravado. Aplique as migrações pendentes a este tenant e depois envie a requisição idêntica de novo com uma nova chave `X-Idempotency`.
BTF-9017	Escopo de organizações indisponível	A lista de organizações do tenant está ausente ou ilegível. Tente novamente com a mesma chave de idempotência quando ela estiver configurada.
BTF-9018	Conjunto de ISPBs do tenant inválido	O tenant vincula mais de um ISPB, então a identidade dele na câmara de compensação não pode ser definida. Nada foi gravado.

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

Eventos

Lista de erros do Bank Transfer

Erros do Bank Transfer

202

400

401

403

404

409

410

422

429

500

502

503

​Erros do Bank Transfer

​202

​400

​401

​403

​404

​409

​410

​422

​429

​500

​502

​503

Erros do Bank Transfer

202

400

401

403

404

409

410

422

429

500

502

503