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:
| Canal | Quando ocorre | Como chega | Efeito no recurso |
|---|---|---|---|
| Síncrono | A detentora recusa a requisição no momento da chamada (POST ou PATCH) | HTTP 4xx/5xx com errors[].code | O recurso não é criado ou não muda de estado |
| Assíncrono | A detentora aceita a requisição e rejeita depois, durante o processamento | HTTP 200 OK na consulta (GET) ou via webhook, com status final e motivo | O recurso vai para REJECTED, REVOKED (consentimento) ou RJCT (pagamento) |
Importante: um mesmo
codepode aparecer nos dois canais.SALDO_INSUFICIENTE, por exemplo, pode ser retornado como422na execução do pagamento ou comorejectionReasonde um pagamento que foi paraRJCTdepois. 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"
}
}| Campo | Tipo | Máx. chars | Obrigatório | Descrição |
|---|---|---|---|---|
errors | array | — | ✅ | Lista de erros (1 a 13 itens) |
errors[].code | string | 255 | ✅ | Código do erro, específico de cada endpoint (ver tabelas abaixo) |
errors[].title | string | 255 | ✅ | Título legível do erro |
errors[].detail | string | 2048 | ✅ | Descrição detalhada da causa |
meta.requestDateTime | string | 20 | ❌ | 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.
| Recurso | Status | Campo com o motivo | Campos de contexto |
|---|---|---|---|
| Consentimento | REJECTED | rejection.reason.code / rejection.reason.detail | rejection.rejectedBy, rejection.rejectedFrom |
| Consentimento | REVOKED | revocation.reason.code / revocation.reason.detail | revocation.revokedBy, revocation.revokedFrom |
| Pagamento | RJCT | rejectionReason.code / rejectionReason.detail | — |
Códigos HTTP
400 Bad Request
400 Bad RequestRequisiçã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
401 UnauthorizedFalha 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
403 ForbiddenToken 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
404 Not FoundRecurso 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
405 Method Not Allowed / 406 Not AcceptableMé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
422 Unprocessable EntityA 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
500 Internal Server Error / 504 Gateway Timeout / 529 Site Is OverloadedFalha 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:
code | Descrição | Como tratar |
|---|---|---|
PARAMETRO_NAO_INFORMADO | Campo obrigatório não informado | Corrija o payload |
PARAMETRO_INVALIDO | Parâmetro fora do formato especificado | Corrija o payload |
DATA_PAGAMENTO_INVALIDA | Data inválida para a configuração do consentimento | Ajuste as datas de início e expiração |
DETALHE_PAGAMENTO_INVALIDO | Parâmetro não obedece às regras de negócio (ex.: limites incoerentes) | Revise limites e configuração |
ERRO_IDEMPOTENCIA | Mesma chave de idempotência com conteúdo diferente | Gere nova chave para um novo pedido |
FUNCIONALIDADE_NAO_HABILITADA | A detentora não oferece Transferências Inteligentes | Ofereça outra instituição ao usuário |
NAO_INFORMADO | Outra 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.code | Descrição | Como tratar |
|---|---|---|
REJEITADO_USUARIO | O usuário rejeitou a autorização na detentora | Encerre o fluxo; nova tentativa só com nova ação do usuário |
TEMPO_EXPIRADO_AUTORIZACAO | O usuário não autorizou dentro do prazo | Crie uma nova Payment Initiation |
CONTAS_ORIGEM_DESTINO_IGUAIS | Conta de origem igual à conta de destino | Peça outra conta de origem |
CONTA_NAO_PERMITE_PAGAMENTO | Conta selecionada não permite pagamentos | Peça outra conta de origem |
AUTENTICACAO_DIVERGENTE | Usuário autenticado na detentora diferente do que criou o consentimento | Confirme o CPF/CNPJ informado na criação |
FLUXO_NAO_SUPORTADO_PRODUTO | Produto não suportado pelo fluxo que iniciou a solicitação | Verifique a configuração do consentimento |
FALHA_INFRAESTRUTURA | Falha interna na detentora | Crie uma nova Payment Initiation após um intervalo |
NAO_INFORMADO | Motivo não informado pela detentora | Nã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).
code | Descrição | Retriável | Como tratar |
|---|---|---|---|
SALDO_INSUFICIENTE | Saldo insuficiente na conta de origem | ✅ | Tente novamente mais tarde, com nova chave de idempotência |
VALOR_ACIMA_LIMITE | Valor acima do limite da instituição (conta ou canal) ou do arranjo | ❌ | Reduza o valor |
VALOR_INVALIDO | Valor inválido para o consentimento | ❌ | Corrija o amount |
LIMITE_PERIODO_VALOR_EXCEDIDO | Limite de valor do período atingido | ⚠️ | Aguarde o próximo período |
LIMITE_PERIODO_QUANTIDADE_EXCEDIDO | Limite de quantidade do período atingido | ⚠️ | Aguarde o próximo período |
LIMITE_VALOR_TRANSACAO_CONSENTIMENTO_EXCEDIDO | Valor acima do limite por transação (transactionLimit) | ❌ | Reduza o valor ou divida em mais transações |
LIMITE_VALOR_TOTAL_CONSENTIMENTO_EXCEDIDO | Valor ultrapassa o limite global (totalAllowedAmount) | ❌ | Crie um novo consentimento |
CONSENTIMENTO_INVALIDO | Consentimento em estado final (CONSUMED, REVOKED ou REJECTED) | ❌ | Crie uma nova Payment Initiation |
CONSENTIMENTO_PENDENTE_AUTORIZACAO | Consentimento em PARTIALLY_ACCEPTED, aguardando múltiplas alçadas | ⚠️ | Aguarde a autorização completa |
PAGAMENTO_DIVERGENTE_CONSENTIMENTO | Dados do pagamento divergem do consentimento | ❌ | Ajuste o pagamento aos dados do consentimento |
DETALHE_PAGAMENTO_INVALIDO | Parâmetro não obedece às regras de negócio | ❌ | Corrija o payload |
PAGAMENTO_RECUSADO_DETENTORA | Pagamento recusado pela detentora (motivo em detail) | ❌ | Avalie o detail |
PAGAMENTO_RECUSADO_SPI | Pagamento recusado pelo SPI | ❌ | Avalie o detail |
FORA_PRAZO_PERMITIDO | Horário ou período não permite o pagamento ou agendamento | ⚠️ | Reenvie dentro da janela permitida |
ERRO_IDEMPOTENCIA | Mesma chave de idempotência com conteúdo diferente | ❌ | Gere nova chave |
PARAMETRO_NAO_INFORMADO / PARAMETRO_INVALIDO | Campo obrigatório ausente ou fora do formato | ❌ | Corrija o payload |
NAO_INFORMADO | Outra 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.code | Descrição | Retriável | Como tratar |
|---|---|---|---|
FALHA_INFRAESTRUTURA_DETENTORA | Falha interna na detentora | ✅ | Execute novo pagamento após um intervalo |
FALHA_INFRAESTRUTURA_SPI | Falha na comunicação com o SPI | ✅ | Execute novo pagamento após um intervalo |
FALHA_INFRAESTRUTURA_ICP | Falha na comunicação com o ICP | ✅ | Execute novo pagamento após um intervalo |
FALHA_INFRAESTRUTURA_PSP_RECEBEDOR | Falha na comunicação com o PSP do recebedor | ✅ | Execute novo pagamento após um intervalo |
TITULARIDADE_INCONSISTENTE | Conta 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
RJCTouCANCnã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}
code | Descrição | Como tratar |
|---|---|---|
CONSENTIMENTO_NAO_PERMITE_CANCELAMENTO | Consentimento em status que não permite cancelamento (CONSUMED ou REJECTED) | Consulte o estado atual; nenhuma ação é necessária |
CAMPO_NAO_PERMITIDO | Campo enviado não pode ser alterado | Envie apenas os campos de cancelamento |
PERMISSAO_INSUFICIENTE | Consentimento com múltiplas alçadas não permite a ação pelo usuário atual | Solicite a ação a um aprovador habilitado |
DETALHE_EDICAO_INVALIDO | A alteração não respeita as regras de negócio | Revise o payload |
FALTAM_SINAIS_OBRIGATORIOS_PLATAFORMA | Sinais obrigatórios da plataforma do usuário não enviados | Envie todos os sinais obrigatórios |
PARAMETRO_NAO_INFORMADO / PARAMETRO_INVALIDO | Campo obrigatório ausente ou fora do formato | Corrija o payload |
Quando o consentimento é revogado, a consulta retorna status = REVOKED com o motivo em revocation.reason.code:
revocation.reason.code | Descrição |
|---|---|
REVOGADO_USUARIO | O usuário pagador solicitou a revogação |
REVOGADO_RECEBEDOR | O recebedor solicitou a revogação à iniciadora (ex.: término de contrato) |
NAO_INFORMADO | Outro 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
Updated about 9 hours ago