Aparência
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
| Status | code | Quando | O que fazer |
|---|---|---|---|
| 401 | AUTH_MISSING_TOKEN | A chamada não traz Authorization: Bearer | Envie o token da aplicação |
| 401 | AUTH_INVALID_TOKEN | O token não verifica, expirou ou não é da aplicação | Peça um token novo no endpoint de token; um token regulado não abre estas rotas |
| 403 | AUTH_INSUFFICIENT_SCOPE | O token não tem o escopo que a operação exige | Confira os escopos da aplicação em Acesso por aplicação |
| 403 | FORBIDDEN | O token não tem o escopo da família de dados pedida | O detail nomeia o escopo; peça-o para a aplicação |
| 503 | AUTH_JWKS_UNAVAILABLE | A plataforma não conseguiu as chaves para verificar tokens | Tente de novo em instantes; se persistir, abra suporte com o x-fapi-interaction-id |
Requisição
| Status | code | Quando | O que fazer |
|---|---|---|---|
| 400 | VALIDATION_ERROR | O corpo ou um parâmetro não segue o contrato | O detail nomeia o campo; corrija-o |
| 400 | AUTHENTICATED_CLIENT_ID_REQUIRED | O token não identifica a aplicação | Use o token da aplicação, de client_credentials |
| 400 | INVALID_AUTHORISATION_SERVER | O servidor de autorização da transmissora não tem issuer | Confira o authorisationServerId no Diretório |
| 400 | REDIRECT_URI_NOT_REGISTERED | O redirectUri não é uma das callbacks do software statement registradas na transmissora | Use uma das software_redirect_uris do software statement |
| 400 | INVALID_PAR_RESPONSE | A transmissora não devolveu um request_uri utilizável | Tente outra vez; se persistir, é da transmissora |
| 400 | INVALID_CERT_BOUND_TOKEN | O token da transmissora não está vinculado ao certificado | Problema da transmissora; abra suporte com o x-fapi-interaction-id |
| 400 | INVALID_OAUTH_STATE | O callback chegou com um state que a plataforma não reconhece | Abra um consentimento novo |
| 400 | INVALID_CALLBACK_RESPONSE | A resposta da transmissora no callback não verificou | Abra um consentimento novo |
| 400 | UNSAFE_OUTBOUND_URL | O endereço da transmissora no Diretório não é um HTTPS público | Escolha outra transmissora ou avise o suporte |
| 413 | PAYLOAD_TOO_LARGE | O corpo passa de 1 MiB (1.048.576 bytes) | Reduza o corpo |
| 415 | UNSUPPORTED_MEDIA_TYPE | O corpo não é application/json | Envie content-type: application/json |
| 422 | UNPROCESSABLE_ENTITY | O callback recebeu um estado de pagamento | Use o callback da iniciadora para pagamentos |
| 422 | o código da transmissora | A 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
| Status | code | Quando | O que fazer |
|---|---|---|---|
| 404 | NOT_FOUND | A conexão ou a agregação não existe, ou é de outra aplicação | Confira o id; cada aplicação só enxerga o que ela mesma abriu |
| 404 | NOT_FOUND | O authorisationServerId não está no Diretório da plataforma (receiver authorisation server <id> not found) | Confira o authorisationServerId no Diretório |
| 409 | CONFLICT | A x-idempotency-key já foi usada com outro corpo, ou o primeiro pedido ainda está em curso | Use uma chave nova para um pedido novo; repita a mesma chave mais tarde |
| 409 | DCR_PENDING | O registro da receptora (DCR) na transmissora ainda está pendente; a resposta traz Retry-After: 60 | Espere os segundos de Retry-After e repita com a mesma x-idempotency-key |
| 409 | CONFLICT | A 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 |
| 409 | CONFLICT | O 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 |
| 409 | CONFLICT | O consentimento não autoriza a família pedida (does not authorize <kind>) | Abra um consentimento com a permissão da família |
| 409 | CONFLICT | O callback chegou para uma conexão que não aguarda mais autorização | A 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
| Status | code | Quando | O que fazer |
|---|---|---|---|
| 503 | INFRA_HTTP | A transmissora não respondeu ou respondeu fora do contrato | Tente de novo; se persistir, é da transmissora |
| 503 | INFRA_FAPI | A troca FAPI com a transmissora falhou | Tente de novo; se persistir, abra suporte com o x-fapi-interaction-id |
| 503 | INFRA_DATABASE | A plataforma não conseguiu gravar ou ler | Tente de novo em instantes; repita a mesma chave de idempotência |
| 500 | INTERNAL_ERROR | Falha inesperada da plataforma | Tente de novo; se persistir, abra suporte com o x-fapi-interaction-id |
| 504 | GATEWAY_TIMEOUT | A chamada passou do prazo de 30 segundos | Tente de novo; numa criação, repita a mesma chave de idempotência |
| 529 | SITE_IS_OVERLOADED | A plataforma está no limite de chamadas simultâneas | Tente de novo em instantes, com espera crescente entre as tentativas |