Códigos de Resposta e Cenários de Erro

Visão Geral

Todas as APIs de compartilhamento de dados do Open Finance Brasil seguem uma estrutura padronizada de resposta para erros. Esta página descreve os códigos HTTP possíveis, a estrutura do payload de erro e orientações de tratamento para cada cenário.

Estrutura Padrão de Erro

Todos os erros retornam um objeto JSON com o array errors e, opcionalmente, meta:

{
  "errors": [
    {
      "code": "CODIGO_DO_ERRO",
      "title": "Título legível do erro",
      "detail": "Descrição detalhada do problema ocorrido."
    }
  ],
  "meta": {
    "requestDateTime": "2024-06-01T10:00:00Z"
  }
}

Campos do Objeto de Erro

Tabela Completa de Códigos HTTP

Detalhamento por Código

200 OK

A requisição foi processada com sucesso. O body contém o recurso solicitado conforme o schema da API correspondente.

202 Accepted

A requisição foi recebida, mas o processamento ainda não foi concluído. Nenhum body é retornado. Ocorre em situações de processamento assíncrono na transmissora.

Como tratar: Implemente retry com backoff exponencial. Aguarde alguns instantes antes de tentar novamente. Não interprete como erro permanente.

400 Bad Request

A requisição está malformada. Pode ocorrer por:

• Atributo obrigatório ausente no body ou na URL
• Formato de campo inválido (ex: UUID malformado no x-fapi-interaction-id)
• Valor fora dos limites permitidos (ex: page-size menor que o mínimo)
• Header x-fapi-interaction-id ausente ou com valor inválido

{
  "errors": [
    {
      "code": "PARAMETRO_INVALIDO",
      "title": "Parâmetro inválido.",
      "detail": "O campo x-fapi-interaction-id deve ser um UUID válido no formato RFC4122."
    }
  ]
}

Como tratar: Revise o payload, headers e query parameters da requisição. Verifique o campo errors[].detail para identificar o atributo problemático.

Atenção sobre x-fapi-interaction-id: Se a transmissora receber um valor inválido neste header, ela deve gerar um novo UUID e retornar 400. A receptora deve acatar o UUID da transmissora na resposta.

401 Unauthorized

Problema na autenticação. Causas comuns:

• Header Authorization ausente
• Bearer token expirado
• Token inválido ou malformado
• Token não vinculado ao consentId correto

{
  "errors": [
    {
      "code": "NAO_AUTORIZADO",
      "title": "Não autorizado.",
      "detail": "Cabeçalho de autenticação ausente ou token inválido."
    }
  ]
}

Como tratar: Renove o access token via fluxo OAuth 2.0. Verifique se o token está sendo enviado corretamente no formato Bearer {token}. Certifique-se de que o token está vinculado ao consentimento correto.

403 Forbidden

O token é válido, mas não possui as permissões necessárias. Causas comuns:

• Permission específica da API não incluída no consentimento (ex: RESOURCES_READ ausente)
• Escopo OAuth incorreto
• Consentimento não está em status AUTHORISED
• Tentativa de acessar dados de outro titular

{
  "errors": [
    {
      "code": "NAO_AUTORIZADO",
      "title": "Acesso proibido.",
      "detail": "O token não possui o escopo necessário para acessar este recurso."
    }
  ]
}

Como tratar: Verifique se a permission necessária foi solicitada na criação do consentimento. Confirme que o consentimento está ativo (AUTHORISED). Consulte a documentação da API específica para verificar as permissions requeridas.

404 Not Found

O recurso não foi encontrado. Causas comuns:

• resourceId, accountId, contractId ou identificador similar inexistente
• Endpoint não implementado pela transmissora
• Versão da API incorreta na URL

{
  "errors": [
    {
      "code": "NAO_ENCONTRADO",
      "title": "Recurso não encontrado.",
      "detail": "O recurso solicitado não existe ou não foi implementado."
    }
  ]
}

Como tratar: Verifique se o identificador do recurso foi obtido corretamente via API Resources. Confirme a versão da API na URL base. Valide se a instituição transmissora implementa o endpoint consultado.

405 Method Not Allowed

O método HTTP utilizado não é suportado pelo endpoint.

{
  "errors": [
    {
      "code": "METODO_NAO_PERMITIDO",
      "title": "Método não permitido.",
      "detail": "O consumidor tentou acessar o recurso com um método não suportado."
    }
  ]
}

Como tratar: Verifique se está usando o método correto (GET, POST etc.) conforme especificado na documentação da API.

406 Not Acceptable

O header Accept contém um tipo de mídia não suportado ou charset diferente de UTF-8.

Como tratar: Use Accept: application/json e certifique-se de que o charset é UTF-8. Remova cabeçalhos Accept com tipos não suportados.

422 Unprocessable Entity

A sintaxe da requisição está correta, mas as instruções não puderam ser processadas por uma regra de negócio. Causas comuns:

• Data fora do intervalo permitido
• Combinação de parâmetros inválida
• Estado do recurso incompatível com a operação

{
  "errors": [
    {
      "code": "DATA_INVALIDA",
      "title": "Data inválida.",
      "detail": "A data informada está fora do intervalo permitido para consulta."
    }
  ]
}

Como tratar: Leia errors[].code e errors[].detail para identificar a regra violada. Não retente sem corrigir os parâmetros.

429 Too Many Requests

O limite de requisições foi atingido. Pode ser:

• Limite por janela de tempo (rate limit da receptora)
• Limite global de requisições concorrentes da transmissora

{
  "errors": [
    {
      "code": "LIMITE_REQUISICOES",
      "title": "Limite de requisições atingido.",
      "detail": "Muitas solicitações foram feitas dentro de um determinado período."
    }
  ]
}

Como tratar: Implemente backoff exponencial: aguarde 1s, depois 2s, depois 4s. Respeite o header Retry-After se presente na resposta. Reduza a frequência de chamadas e considere caching local.

500 Internal Server Error

Falha interna na transmissora. Pode ocorrer no gateway da API ou em um microsserviço interno.

Como tratar: Tente novamente após alguns segundos. Se o erro persistir, acione o suporte da instituição transmissora. Registre o x-fapi-interaction-id da resposta para facilitar a investigação.

504 Gateway Timeout

A requisição não foi respondida dentro do tempo limite pelo gateway ou pela transmissora.

Como tratar: Antes de retentar, consulte o status do recurso para verificar se a operação foi processada (evite duplicidade). Aguarde pelo menos 5 segundos antes de uma nova tentativa.

529 Site Is Overloaded

Código não-padrão HTTP utilizado pelo Open Finance Brasil para indicar sobrecarga com limite máximo de TPS global atingido.

Como tratar: Trate como 429. Implemente backoff exponencial e reduza a taxa de chamadas. Não retente imediatamente.

Fluxo de Decisão para Tratamento de Erros

flowchart TD
    A["Resposta da API"] --> B{Código HTTP}

    B -->|200| C["Processar resposta normalmente"]
    B -->|202| D["Retry com backoff\nAguarde e tente novamente"]
    B -->|400| E["Revisar payload, headers\ne query parameters"]
    B -->|401| F["Renovar access token\nvia OAuth 2.0"]
    B -->|403| G["Verificar permissions\nno consentimento"]
    B -->|404| H["Verificar identificador\ne versão da API"]
    B -->|405| I["Verificar método HTTP\ncorreto na documentação"]
    B -->|406| J["Corrigir header Accept\npara application/json"]
    B -->|422| K["Ler errors[].code\nCorrigir regra violada\nNão retente sem correção"]
    B -->|429 ou 529| L["Backoff exponencial\nRespeitar Retry-After"]
    B -->|500| M["Retry após 5s\nRegistrar x-fapi-interaction-id"]
    B -->|504| N["Consultar status\nantes de retentar"]

    style C fill:#d5f5d5,stroke:#27ae60,color:#333
    style D fill:#fef9c3,stroke:#f39c12,color:#333
    style E fill:#f5c6c6,stroke:#c0392b,color:#333
    style F fill:#f5c6c6,stroke:#c0392b,color:#333
    style G fill:#f5c6c6,stroke:#c0392b,color:#333
    style H fill:#f5c6c6,stroke:#c0392b,color:#333
    style I fill:#f5c6c6,stroke:#c0392b,color:#333
    style J fill:#f5c6c6,stroke:#c0392b,color:#333
    style K fill:#f5c6c6,stroke:#c0392b,color:#333
    style L fill:#fef9c3,stroke:#f39c12,color:#333
    style M fill:#fef9c3,stroke:#f39c12,color:#333
    style N fill:#fef9c3,stroke:#f39c12,color:#333

Erros Retriáveis vs. Definitivos

Boas Práticas Gerais

Sempre registre o x-fapi-interaction-id de toda requisição e resposta. É o identificador de correlação para investigação de incidentes junto à transmissora.

Nunca exponha errors[].detail diretamente ao usuário final. Use os códigos para mapear mensagens amigáveis na sua interface.

Implemente circuit breaker para erros 500 e 504 recorrentes. Após N falhas consecutivas, pause as chamadas por um intervalo antes de tentar novamente.

Para erros 403: verifique primeiro se a permission necessária foi incluída no consentimento. Recriar o consentimento com a permission correta é mais rápido do que investigar outros problemas.

Para erros 404: use sempre o resourceId retornado pela API Resources como identificador nas APIs de produto. Nunca construa IDs manualmente.