Skip to content

Erros das APIs de aplicação da receptora ​

As rotas de /banking-receiver respondem os erros no envelope do Open Finance Brasil, com content-type: application/json; charset=utf-8:

json
{
  "errors": [
    {
      "code": "NOT_FOUND",
      "title": "Not Found",
      "detail": "receiver-consent <id> not found"
    }
  ],
  "meta": { "requestDateTime": "2026-10-22T12:00:00Z" }
}

O status HTTP diz a classe do erro, e errors[0].code diz o motivo. Quando a recusa é de um campo com código próprio, como UNSAFE_OUTBOUND_URL, é esse o code que vem no envelope, e o detail descreve o campo. Ao pedir suporte, envie o x-fapi-interaction-id da chamada, que a resposta devolve no cabeçalho.

Autenticação e escopo ​

StatuscodeQuandoO que fazer
401AUTH_MISSING_TOKENA chamada não traz Authorization: BearerEnvie o token da aplicação
401AUTH_INVALID_TOKENO token não verifica, expirou ou não é da aplicaçãoPeça um token novo no endpoint de token; um token regulado não abre estas rotas
403AUTH_INSUFFICIENT_SCOPEO token não tem o escopo que a operação exigeConfira os escopos da aplicação em Acesso por aplicação
403FORBIDDENO token não tem o escopo da família de dados pedidaO detail nomeia o escopo; peça-o para a aplicação
503AUTH_JWKS_UNAVAILABLEA plataforma não conseguiu as chaves para verificar tokensTente de novo em instantes; se persistir, abra suporte com o x-fapi-interaction-id

Requisição ​

StatuscodeQuandoO que fazer
400VALIDATION_ERRORO corpo ou um parâmetro não segue o contratoO detail nomeia o campo; corrija-o
400AUTHENTICATED_CLIENT_ID_REQUIREDO token não identifica a aplicaçãoUse o token da aplicação, de client_credentials
400INVALID_AUTHORISATION_SERVERO servidor de autorização da transmissora não tem issuerConfira o authorisationServerId no Diretório
400REDIRECT_URI_NOT_REGISTEREDO redirectUri não é uma das callbacks do software statement registradas na transmissoraUse uma das software_redirect_uris do software statement
400INVALID_PAR_RESPONSEA transmissora não devolveu um request_uri utilizávelTente outra vez; se persistir, é da transmissora
400INVALID_CERT_BOUND_TOKENO token da transmissora não está vinculado ao certificadoProblema da transmissora; abra suporte com o x-fapi-interaction-id
400INVALID_OAUTH_STATEO callback chegou com um state que a plataforma não reconheceAbra um consentimento novo
400INVALID_CALLBACK_RESPONSEA resposta da transmissora no callback não verificouAbra um consentimento novo
400UNSAFE_OUTBOUND_URLO endereço da transmissora no Diretório não é um HTTPS públicoEscolha outra transmissora ou avise o suporte
413PAYLOAD_TOO_LARGEO corpo passa de 1 MiB (1.048.576 bytes)Reduza o corpo
415UNSUPPORTED_MEDIA_TYPEO corpo não é application/jsonEnvie content-type: application/json
422UNPROCESSABLE_ENTITYO callback recebeu um estado de pagamentoUse o callback da iniciadora para pagamentos
422o código da transmissoraA transmissora recusou criar o consentimento (holder refused the consent request)Corrija as permissões ou a data de expiração e abra um consentimento novo

Na recusa da transmissora, o code é o que ela devolveu: SEM_PERMISSOES_FUNCIONAIS_RESTANTES, INFORMACOES_PJ_NAO_INFORMADAS, PERMISSOES_PJ_INCORRETAS, PERMISSAO_PF_PJ_EM_CONJUNTO, COMBINACAO_PERMISSOES_INCORRETA, DATA_EXPIRACAO_INVALIDA ou ERRO_NAO_MAPEADO.

Estado ​

StatuscodeQuandoO que fazer
404NOT_FOUNDA conexão ou a agregação não existe, ou é de outra aplicaçãoConfira o id; cada aplicação só enxerga o que ela mesma abriu
404NOT_FOUNDO authorisationServerId não está no Diretório da plataforma (receiver authorisation server <id> not found)Confira o authorisationServerId no Diretório
409CONFLICTA x-idempotency-key já foi usada com outro corpo, ou o primeiro pedido ainda está em cursoUse uma chave nova para um pedido novo; repita a mesma chave mais tarde
409DCR_PENDINGO registro da receptora (DCR) na transmissora ainda está pendente; a resposta traz Retry-After: 60Espere os segundos de Retry-After e repita com a mesma x-idempotency-key
409CONFLICTA plataforma não conseguiu renovar o token expirado da transmissora (receiver token is expired)O cliente final precisa autorizar de novo: abra um consentimento novo
409CONFLICTO token da transmissora está vinculado a um certificado de transporte que a plataforma não monta mais, por exemplo depois de uma rotação (receiver token is bound to a certificate no longer mounted)Abra um consentimento novo
409CONFLICTO consentimento não autoriza a família pedida (does not authorize <kind>)Abra um consentimento com a permissão da família
409CONFLICTO callback chegou para uma conexão que não aguarda mais autorizaçãoA conexão já foi tratada; consulte o status dela

A plataforma renova sozinha, uma vez, o token expirado da transmissora antes de ler os dados. Se a renovação falhar por outro motivo, a resposta é 503 INFRA_FAPI (ou INFRA_DATABASE), e a chamada pode ser repetida.

Indisponibilidade ​

StatuscodeQuandoO que fazer
503INFRA_HTTPA transmissora não respondeu ou respondeu fora do contratoTente de novo; se persistir, é da transmissora
503INFRA_FAPIA troca FAPI com a transmissora falhouTente de novo; se persistir, abra suporte com o x-fapi-interaction-id
503INFRA_DATABASEA plataforma não conseguiu gravar ou lerTente de novo em instantes; repita a mesma chave de idempotência
500INTERNAL_ERRORFalha inesperada da plataformaTente de novo; se persistir, abra suporte com o x-fapi-interaction-id
504GATEWAY_TIMEOUTA chamada passou do prazo de 30 segundosTente de novo; numa criação, repita a mesma chave de idempotência
529SITE_IS_OVERLOADEDA plataforma está no limite de chamadas simultâneasTente de novo em instantes, com espera crescente entre as tentativas

Finnest Power — plataforma Open Finance Brasil e Open Insurance Brasil. Contato: oi@finnest.com.br