Sweeping Accounts - Erros e Códigos HTTP

Como interpretar e tratar os erros de Transferências Inteligentes em cada etapa da máquina de estados

Visão Geral

Os erros de Transferências Inteligentes (Sweeping Accounts) seguem a especificação de Pagamentos Automáticos do Open Finance Brasil (v2.2.1). Esta página descreve como cada erro chega à sua aplicação, quais códigos HTTP e code podem ser retornados em cada etapa e como tratar cada um deles, relacionando-os aos estados descritos em Sweeping Accounts - Máquina de Estados.


Dois canais de erro: síncrono e assíncrono

Um mesmo problema pode chegar por dois caminhos diferentes, dependendo do momento em que a detentora o identifica:

CanalQuando ocorreComo chegaEfeito no recurso
SíncronoA detentora recusa a requisição no momento da chamada (POST ou PATCH)HTTP 4xx/5xx com errors[].codeO recurso não é criado ou não muda de estado
AssíncronoA detentora aceita a requisição e rejeita depois, durante o processamentoHTTP 200 OK na consulta (GET) ou via webhook, com status final e motivoO recurso vai para REJECTED, REVOKED (consentimento) ou RJCT (pagamento)

Importante: um mesmo code pode aparecer nos dois canais. SALDO_INSUFICIENTE, por exemplo, pode ser retornado como 422 na execução do pagamento ou como rejectionReason de um pagamento que foi para RJCT depois. Trate sempre os dois caminhos.


Estrutura do corpo de erro

Erros síncronos retornam um objeto JSON no padrão Open Finance Brasil:

{
  "errors": [
    {
      "code": "LIMITE_PERIODO_VALOR_EXCEDIDO",
      "title": "Limite do período excedido.",
      "detail": "A transação não pode ser realizada pois o valor parametrizado no consentimento foi excedido."
    }
  ],
  "meta": {
    "requestDateTime": "2026-11-18T17:00:00Z"
  }
}
CampoTipoMáx. charsObrigatórioDescrição
errorsarray—✅Lista de erros (1 a 13 itens)
errors[].codestring255✅Código do erro, específico de cada endpoint (ver tabelas abaixo)
errors[].titlestring255✅Título legível do erro
errors[].detailstring2048✅Descrição detalhada da causa
meta.requestDateTimestring20❌Data e hora da requisição em UTC (RFC-3339)

Erros assíncronos não usam esse corpo: o motivo vem dentro do próprio recurso consultado.

RecursoStatusCampo com o motivoCampos de contexto
ConsentimentoREJECTEDrejection.reason.code / rejection.reason.detailrejection.rejectedBy, rejection.rejectedFrom
ConsentimentoREVOKEDrevocation.reason.code / revocation.reason.detailrevocation.revokedBy, revocation.revokedFrom
PagamentoRJCTrejectionReason.code / rejectionReason.detail—

Códigos HTTP

400 Bad Request

Requisição malformada: assinatura da mensagem inválida (BAD_SIGNATURE), parâmetro de path ou query inválido (ex.: CPF ausente ou inválido na listagem) ou header obrigatório ausente.

Como tratar: corrija a requisição antes de reenviar. Não faça retentativa automática.

401 Unauthorized

Falha de autenticação: token ausente, expirado ou inválido (UNAUTHORIZED) ou certificado incorreto no processo de DCR (INVALID_CLIENT).

Como tratar: renove o application_token e repita a chamada uma única vez. Se persistir, verifique as credenciais.

403 Forbidden

Token válido, mas sem permissão para a operação: claims do JWT inválidas (aud, iss, iat, jti) ou reuso de jti (INVALID_CLIENT).

Como tratar: não repita a mesma requisição. Gere uma nova requisição com claims e jti novos.

404 Not Found

Recurso inexistente (ex.: paymentInitiationId não encontrado) ou versão de API incorreta na URL.

Como tratar: confira o identificador e a versão do endpoint.

405 Method Not Allowed / 406 Not Acceptable

Método HTTP não suportado pelo endpoint, ou header Accept com tipo de mídia não suportado.

Como tratar: ajuste o método ou o header Accept conforme a referência do endpoint.

422 Unprocessable Entity

A requisição está correta sintaticamente, mas uma regra de negócio impede o processamento. É o principal erro de Transferências Inteligentes: o code indica a causa e varia por etapa (ver Erros por etapa).

Como tratar: leia errors[].code e siga a orientação da tabela da etapa correspondente. Em cancelamentos, consulte o recurso (GET) para verificar o estado atual antes de qualquer nova ação.

500 Internal Server Error / 504 Gateway Timeout / 529 Site Is Overloaded

Falha interna, tempo limite excedido ou limite global de TPS atingido na detentora. O 529 é um código não padrão do Open Finance Brasil.

Como tratar: faça retentativa com backoff exponencial. Em POST, reutilize a mesma chave de idempotência para não duplicar o recurso. Antes de reenviar uma execução de pagamento, consulte o consentimento para verificar se o pagamento já foi criado.

429 Too Many Requests: não faz parte do contrato de Pagamentos Automáticos v2.2.1, mas pode ser retornado por limites de requisição da plataforma. Trate com backoff.


Erros por etapa

1. Criação da Payment Initiation (consentimento)

POST /payment-initiation → na detentora: POST /recurring-consents

Nesta etapa a detentora não valida dados do usuário (saldo, conta bloqueada etc.). Erros de negócio retornam 422:

codeDescriçãoComo tratar
PARAMETRO_NAO_INFORMADOCampo obrigatório não informadoCorrija o payload
PARAMETRO_INVALIDOParâmetro fora do formato especificadoCorrija o payload
DATA_PAGAMENTO_INVALIDAData inválida para a configuração do consentimentoAjuste as datas de início e expiração
DETALHE_PAGAMENTO_INVALIDOParâmetro não obedece às regras de negócio (ex.: limites incoerentes)Revise limites e configuração
ERRO_IDEMPOTENCIAMesma chave de idempotência com conteúdo diferenteGere nova chave para um novo pedido
FUNCIONALIDADE_NAO_HABILITADAA detentora não oferece Transferências InteligentesOfereça outra instituição ao usuário
NAO_INFORMADOOutra validação não explicitada (ex.: suspeita de fraude)Não repita automaticamente

2. Autorização do consentimento pelo usuário

AWAITING_AUTHORISATION → REJECTED

O erro é assíncrono: a consulta retorna 200 OK com status = REJECTED e o motivo em rejection.reason.code.

rejection.reason.codeDescriçãoComo tratar
REJEITADO_USUARIOO usuário rejeitou a autorização na detentoraEncerre o fluxo; nova tentativa só com nova ação do usuário
TEMPO_EXPIRADO_AUTORIZACAOO usuário não autorizou dentro do prazoCrie uma nova Payment Initiation
CONTAS_ORIGEM_DESTINO_IGUAISConta de origem igual à conta de destinoPeça outra conta de origem
CONTA_NAO_PERMITE_PAGAMENTOConta selecionada não permite pagamentosPeça outra conta de origem
AUTENTICACAO_DIVERGENTEUsuário autenticado na detentora diferente do que criou o consentimentoConfirme o CPF/CNPJ informado na criação
FLUXO_NAO_SUPORTADO_PRODUTOProduto não suportado pelo fluxo que iniciou a solicitaçãoVerifique a configuração do consentimento
FALHA_INFRAESTRUTURAFalha interna na detentoraCrie uma nova Payment Initiation após um intervalo
NAO_INFORMADOMotivo não informado pela detentoraNão repita automaticamente

rejectedBy indica quem rejeitou (INICIADORA, USUARIO, DETENTORA) e rejectedFrom, o canal (INICIADORA, DETENTORA).

3. Execução do pagamento Pix

POST /payment-initiation/:paymentInitiationId/payments → na detentora: POST /pix/recurring-payments

Se a detentora recusar na chamada, o retorno é 422 e o pagamento não é criado. Se aceitar, o pagamento nasce em PDNG e pode ir depois para RJCT (ver etapa 4).

codeDescriçãoRetriávelComo tratar
SALDO_INSUFICIENTESaldo insuficiente na conta de origem✅Tente novamente mais tarde, com nova chave de idempotência
VALOR_ACIMA_LIMITEValor acima do limite da instituição (conta ou canal) ou do arranjo❌Reduza o valor
VALOR_INVALIDOValor inválido para o consentimento❌Corrija o amount
LIMITE_PERIODO_VALOR_EXCEDIDOLimite de valor do período atingido⚠️Aguarde o próximo período
LIMITE_PERIODO_QUANTIDADE_EXCEDIDOLimite de quantidade do período atingido⚠️Aguarde o próximo período
LIMITE_VALOR_TRANSACAO_CONSENTIMENTO_EXCEDIDOValor acima do limite por transação (transactionLimit)❌Reduza o valor ou divida em mais transações
LIMITE_VALOR_TOTAL_CONSENTIMENTO_EXCEDIDOValor ultrapassa o limite global (totalAllowedAmount)❌Crie um novo consentimento
CONSENTIMENTO_INVALIDOConsentimento em estado final (CONSUMED, REVOKED ou REJECTED)❌Crie uma nova Payment Initiation
CONSENTIMENTO_PENDENTE_AUTORIZACAOConsentimento em PARTIALLY_ACCEPTED, aguardando múltiplas alçadas⚠️Aguarde a autorização completa
PAGAMENTO_DIVERGENTE_CONSENTIMENTODados do pagamento divergem do consentimento❌Ajuste o pagamento aos dados do consentimento
DETALHE_PAGAMENTO_INVALIDOParâmetro não obedece às regras de negócio❌Corrija o payload
PAGAMENTO_RECUSADO_DETENTORAPagamento recusado pela detentora (motivo em detail)❌Avalie o detail
PAGAMENTO_RECUSADO_SPIPagamento recusado pelo SPI❌Avalie o detail
FORA_PRAZO_PERMITIDOHorário ou período não permite o pagamento ou agendamento⚠️Reenvie dentro da janela permitida
ERRO_IDEMPOTENCIAMesma chave de idempotência com conteúdo diferente❌Gere nova chave
PARAMETRO_NAO_INFORMADO / PARAMETRO_INVALIDOCampo obrigatório ausente ou fora do formato❌Corrija o payload
NAO_INFORMADOOutra validação não explicitada (ex.: suspeita de fraude)❌Não repita automaticamente

Legenda: ✅ pode ser repetido · ⚠️ pode ser repetido depois que a condição mudar · ❌ exige correção ou nova ação do usuário

4. Processamento e liquidação do pagamento

PDNG / SCHD / ACCP → RJCT

O erro é assíncrono: a consulta (ou o webhook) retorna o pagamento com status = RJCT e o motivo em rejectionReason.code. Além dos códigos semânticos da etapa 3 (exceto CONSENTIMENTO_PENDENTE_AUTORIZACAO, ERRO_IDEMPOTENCIA e PARAMETRO_*), podem aparecer:

rejectionReason.codeDescriçãoRetriávelComo tratar
FALHA_INFRAESTRUTURA_DETENTORAFalha interna na detentora✅Execute novo pagamento após um intervalo
FALHA_INFRAESTRUTURA_SPIFalha na comunicação com o SPI✅Execute novo pagamento após um intervalo
FALHA_INFRAESTRUTURA_ICPFalha na comunicação com o ICP✅Execute novo pagamento após um intervalo
FALHA_INFRAESTRUTURA_PSP_RECEBEDORFalha na comunicação com o PSP do recebedor✅Execute novo pagamento após um intervalo
TITULARIDADE_INCONSISTENTEConta de destino não pertence mais ao CPF/CNPJ do consentimento (erro BE01 do PSP recebedor)❌Crie novo consentimento com a conta correta

Limites: pagamentos em RJCT ou CANC não são considerados no cálculo dos limites do consentimento.

5. Consulta

GET /payment-initiation e GET /payment-initiation/:paymentInitiationId

Retornam apenas erros de transporte: 400 (ex.: CPF ausente ou inválido na listagem), 401 e 404. Um 200 OK pode conter consentimento ou pagamento em estado de erro: verifique sempre status e os campos de motivo.

6. Cancelamento do consentimento

PATCH /payment-initiation/:paymentInitiationId → na detentora: PATCH /recurring-consents/{recurringConsentId}

codeDescriçãoComo tratar
CONSENTIMENTO_NAO_PERMITE_CANCELAMENTOConsentimento em status que não permite cancelamento (CONSUMED ou REJECTED)Consulte o estado atual; nenhuma ação é necessária
CAMPO_NAO_PERMITIDOCampo enviado não pode ser alteradoEnvie apenas os campos de cancelamento
PERMISSAO_INSUFICIENTEConsentimento com múltiplas alçadas não permite a ação pelo usuário atualSolicite a ação a um aprovador habilitado
DETALHE_EDICAO_INVALIDOA alteração não respeita as regras de negócioRevise o payload
FALTAM_SINAIS_OBRIGATORIOS_PLATAFORMASinais obrigatórios da plataforma do usuário não enviadosEnvie todos os sinais obrigatórios
PARAMETRO_NAO_INFORMADO / PARAMETRO_INVALIDOCampo obrigatório ausente ou fora do formatoCorrija o payload

Quando o consentimento é revogado, a consulta retorna status = REVOKED com o motivo em revocation.reason.code:

revocation.reason.codeDescrição
REVOGADO_USUARIOO usuário pagador solicitou a revogação
REVOGADO_RECEBEDORO recebedor solicitou a revogação à iniciadora (ex.: término de contrato)
NAO_INFORMADOOutro motivo não explicitado (ex.: suspeita de fraude)

revokedBy indica quem revogou (INICIADORA, USUARIO, DETENTORA) e revokedFrom, o canal (INICIADORA, DETENTORA).


Fluxo de decisão

flowchart TD
    A[Chamada à API] --> B{HTTP status}
    B -- 2xx --> C{status do recurso}
    C -- AUTHORISED / PDNG / SCHD / ACSC --> D[Sucesso ou em andamento]
    C -- REJECTED / REVOKED / RJCT --> E[Erro assíncrono: ler reason.code]
    B -- 400 / 404 / 405 / 406 --> F[Corrigir requisição]
    B -- 401 --> G[Renovar token e repetir 1x]
    B -- 403 --> H[Gerar nova requisição com claims novas]
    B -- 422 --> I[Erro de negócio: ler errors.code]
    B -- 500 / 504 / 529 --> J[Retentativa com backoff e mesma chave de idempotência]
    E --> K{Retriável?}
    I --> K
    K -- Sim --> L[Nova tentativa após intervalo]
    K -- Não --> M[Corrigir ou pedir nova ação do usuário]

Referências


Did this page help you?