Procurando a documentação anterior?Acesse v1.docs.pluggy.ai
PluggyDocs

Códigos de Erro

Os códigos de status HTTP que a API Pluggy retorna, o que cada um significa e a estrutura de um corpo de erro.

Ver como Markdown

Corpo do erro#

Cada erro, em cada endpoint, tem esta forma:

CampoSignificado
codeO status HTTP, repetido. Sempre presente.
messageUma frase para uma pessoa. Sempre presente; não estável.
codeDescriptionUm identificador estável para o erro específico, quando o endpoint distingue vários. Baseie-se nisso, não em message.
dataDetalhe extra para alguns erros — por exemplo, os Itens que já existem ao criar um que duplicaria uma conexão.

Códigos de status#

StatusSignificadoGeralmente por causa de
400 Bad RequestA solicitação é inválida.Um campo ausente ou malformado (INVALID_PARAMETERS).
401 UnauthorizedA credencial está ausente, errada ou expirada.Uma Chave da API que passou suas 2 horas, ou clientId/clientSecret errados em POST /auth (CLIENT_KEYS_UNAUTHORIZED, CLIENT_DISABLED).
403 ForbiddenA credencial não pode acessar este recurso.Um Connect Token usado fora de seu escopo — veja AutenticaçãoAPI.
404 Not FoundNenhum recurso desse tipo.Um id que não existe.
405 Method Not AllowedO endpoint não suporta este verbo.
406 Not AcceptableUm formato diferente de JSON foi solicitado.
409 ConflictA solicitação contradiz o estado atual do recurso.Um conflito ao atualizar um Item — veja PATCH /items/{id}API.
429 Too Many RequestsUm limite de taxa foi excedido.Veja Limites de TaxaAPI para os limites e o cabeçalho Retry-After.
500 Internal Server ErrorAlgo falhou do nosso lado.Tente novamente mais tarde.
503 Service UnavailableTemporariamente indisponível.Manutenção, ou uma instituição financeira que está temporariamente sem resposta (BALANCE_INSTITUTION_RATE_LIMITED). Tente novamente mais tarde.

A página de cada endpoint nesta referência lista os status que ele retorna e, onde a API os distingue, os valores de codeDescription.

Parâmetros inválidos#

codeDescriptionStatusMensagemO que fazer
INVALID_PARAMETERS400Nomeia o parâmetro e o problema — por exemplo accountId deve ser um UUID, property pageSize não deve existir ou page deve ser um inteiro entre 1 e 1000000.Um parâmetro de caminho, consulta ou corpo está ausente, malformado ou não aceito pelo endpoint. Corrija o parâmetro nomeado na mensagem; tentar a mesma solicitação retorna o mesmo erro.

Parâmetros de consulta desconhecidos são rejeitados a partir de 2026-11-23

A partir de 2026-11-23 16:00 horário de Brasília (19:00 UTC), endpoints GET rejeitam parâmetros de consulta que não aceitam com 400 INVALID_PARAMETERS e a mensagem Parâmetro de consulta 'x' não é aceito por este endpoint. Antes dessa data, parâmetros de consulta desconhecidos são ignorados silenciosamente. Envie apenas os parâmetros listados na página de referência de cada endpoint.

Criando e atualizando um Item#

Esses retornam de POST /itemsAPI e PATCH /items/{id}API. Onde o texto abaixo mostra um :placeholder, a mensagem real carrega o valor — uma frequência, uma espera, um nome de parâmetro.

codeDescriptionStatusMensagemO que fazer
PARAMETERS_NOT_PROVIDED400parâmetros não foram fornecidosEnvie as credenciais da conexão para sincronizar o item.
ITEM_ALREADY_UPDATING400Uma atualização já está em andamento, aguarde até que a última execução termineEste item está sincronizando. Aguarde a execução terminar — sucesso ou erro — antes de acionar outra.
ITEM_IS_ALREADY_UPDATING400Há um item ativo para o conjunto de credenciais que não terminou de executarO mesmo conjunto de credenciais está sincronizando em outro item. Aguarde por ele, para que duas sessões não sejam abertas com a instituição ao mesmo tempo.
CLIENT_IS_UPDATING_BEFORE_ALLOWED_FREQUENCY409Atualizações do cliente neste item são permitidas no máximo a cada :minUpdateFrequencyAllowedInHours horas. A última atualização foi em :lastUpdatedAtAguarde até que a frequência mínima tenha passado desde a última atualização. O limite é por equipe e ajustável — pergunte ao suporte se seu caso de uso precisar de um mais curto.
LAST_EXECUTION_HAD_LOGIN_ERROR400A última execução teve um erro de login, você deve atualizar os parâmetrosA última sincronização falhou ao fazer login. Envie novas credenciais antes de atualizar novamente.
TOO_MANY_CONSECUTIVE_LOGIN_FAILURES400deve aguardar pelo menos :readableBackoffTime após :maxConsecutiveFailedLoginAttempts erros de login consecutivos, a última tentativa foi em :lastExecutionEndedAt (pode tentar novamente após: :canRetryAfterDate)Um cooldown após erros de login repetidos, para que a conta do usuário não seja bloqueada pela instituição. Tente novamente após o tempo na mensagem.
TOO_MANY_CONSECUTIVE_ERRORS400Houve mais de 5 sincronizações falhadas, entre em contato com o suporteA conexão falhou muitas vezes seguidas. Relate ao suporte com o itemId.
ITEM_IN_ERROR_COOLDOWN409Este conjunto de credenciais falhou recentemente ao conectar e está em um período de cooldown, por favor, tente novamente mais tardeEssas credenciais falharam recentemente e estão em um cooldown. Tente novamente após passar.
CONNECTOR_OFFLINE409este conector está offline neste momentoO conector não está aceitando execuções agora. Tente novamente mais tarde — veja status.pluggy.ai.
CONNECTOR_REQUIRED_PARAMETER_VALIDATION_ERROR400O parâmetro :parameter é necessário para ser renovado para atualização do item.O conector agora requer esse parâmetro novamente. Envie-o para atualizar a conexão.
ITEM_ORIGINAL_CONNECTED_WITH_DIFFERENT_ACCOUNT409O Item foi originalmente conectado com uma conta diferente, por favor, use a conta originalAs credenciais agora apontam para uma conta diferente da qual o item foi criado. Use a conta original ou crie um novo item.
ITEM_CREATION_LIMIT_EXCEEDED409O cliente excedeu o limite de criação de itens (:itemsLimit itens) para o nível de assinatura atual.Você atingiu o limite de itens da sua assinatura. O limite se aplica a cada aplicação que não está em uma assinatura de produção, incluindo a aplicação Demo criada com sua equipe; itens do Sandbox (Pluggy Bank) não contam para isso. Exclua itens não utilizados ou entre em contato com o suporte.
CLIENT_HAS_ITEM_UPDATES_DISABLED409O cliente tem atualizações de itens desativadasAtualizações foram desativadas para a equipe. Entre em contato com o suporte.
CREATE_ITEMS_API_FREE_DISABLED400A assinatura gratuita só pode criar itens através do nosso Connect WidgetNa assinatura gratuita, itens são criados através do Connect Widget.
SANDBOX_CLIENT_ITEM_UPDATE_NOT_ALLOWED400O nível de assinatura atual do cliente só pode atualizar itens do Sandbox (Pluggy Bank)Seu nível de assinatura só permite atualizar itens do Sandbox (Pluggy Bank).
TRIAL_CLIENT_ITEM_CREATE_NOT_ALLOWED400Clientes em teste só podem criar itens do Sandbox (Pluggy Bank)Durante o teste, itens só podem ser criados em conectores do Sandbox (Pluggy Bank) e no conector MeuPluggy. Use esses enquanto estiver em teste, ou atualize sua assinatura para conectar outras instituições.
CLIENT_PLAN_REAL_CONNECTORS_NOT_ALLOWED400A assinatura atual do cliente não permite conectar contas reais, apenas itens do Sandbox (Pluggy Bank) e Meu PluggySua assinatura não permite conectar contas reais. Aplicações gratuitas só podem conectar conectores do Sandbox (Pluggy Bank) e MeuPluggy; aplicações de teste só listam esses conectores até que o acesso a dados reais seja aprovado para o teste. Atualize sua assinatura ou entre em contato com o suporte para conectar outras instituições.
MEU_PLUGGY_ITEM_UPDATE_NOT_ALLOWED400O item MeuPluggy não pode ser atualizadoItens MeuPluggy são mantidos atualizados pelo próprio MeuPluggy e não podem ser atualizados com PATCH /items/{id}. Leia os dados com os endpoints do item; não há nada a acionar.

Quem deve agir#

A maioria desses compartilha o status 400, então baseie-se em codeDescription, não no status. Apenas alguns deles precisam do usuário final, e apenas os "aguarde e tente novamente" desaparecem ao tentar novamente: o resto precisa de uma mudança em sua solicitação, sua assinatura ou um ticket de suporte. Em todos os casos, continue mostrando os dados que você já possui.

Esta tabela cobre todos os códigos acima e todos os erros de MFA abaixo.

codeDescriptionRequer o usuárioQuem age
PARAMETERS_NOT_PROVIDEDSimO usuário — insere as credenciais da conexão.
LAST_EXECUTION_HAD_LOGIN_ERRORSimO usuário — insere novas credenciais.
CONNECTOR_REQUIRED_PARAMETER_VALIDATION_ERRORSimO usuário — fornece o parâmetro nomeado na mensagem novamente.
ITEM_ORIGINAL_CONNECTED_WITH_DIFFERENT_ACCOUNTSimO usuário — reconecta com a conta original ou cria um novo item.
ITEM_MFA_EXPIREDSimO usuário — inicia uma nova atualização e insere um novo valor de MFA.
MFA_PARAMERTER_WAS_ALREADY_USED_ERRORSimO usuário — insere um novo valor de MFA.
ITEM_ALREADY_UPDATINGNãoNinguém — aguarde a execução em andamento e tente novamente.
ITEM_IS_ALREADY_UPDATINGNãoNinguém — aguarde a execução do outro item e tente novamente.
CLIENT_IS_UPDATING_BEFORE_ALLOWED_FREQUENCYNãoNinguém — aguarde a frequência mínima e tente novamente.
TOO_MANY_CONSECUTIVE_LOGIN_FAILURESNãoNinguém — aguarde o cooldown na mensagem e tente novamente.
ITEM_IN_ERROR_COOLDOWNNãoNinguém — aguarde o cooldown e tente novamente.
CONNECTOR_OFFLINENãoNinguém — tente novamente quando o conector voltar online.
ITEM_MFA_PARAMETER_EXPECTED_MISMATCHNãoSua integração — envie o valor sob o nome do parâmetro na mensagem.
ITEM_MFA_NOT_FOUNDNãoSua integração — envie MFA apenas enquanto o item estiver aguardando por isso.
ITEM_MFA_ALREADY_PROVIDEDNãoSua integração — nada a enviar; o MFA já foi recebido.
MISSING_MFA_PARAMETER_DATANãoSua integração — a solicitação não tinha parâmetros de MFA; envie-os.
MISSING_MFA_PARAMETER_VALUENãoSua integração — um parâmetro foi enviado vazio; envie o valor (se o usuário deixou o campo em branco, pergunte a ele antes de enviar).
TOO_MANY_CONSECUTIVE_ERRORSNãoSuporte Pluggy — relate com o itemId.
ITEM_CREATION_LIMIT_EXCEEDEDNãoSua assinatura — exclua itens não utilizados ou entre em contato com o suporte.
CLIENT_HAS_ITEM_UPDATES_DISABLEDNãoSuporte Pluggy.
CREATE_ITEMS_API_FREE_DISABLEDNãoSua assinatura — crie itens através do Connect Widget ou atualize.
SANDBOX_CLIENT_ITEM_UPDATE_NOT_ALLOWEDNãoSua assinatura.
TRIAL_CLIENT_ITEM_CREATE_NOT_ALLOWEDNãoSua assinatura — use conectores do Sandbox durante o teste ou atualize.
CLIENT_PLAN_REAL_CONNECTORS_NOT_ALLOWEDNãoSua assinatura — use conectores do Sandbox ou MeuPluggy, ou atualize.
MEU_PLUGGY_ITEM_UPDATE_NOT_ALLOWEDNãoSua integração — não envie atualizações para itens MeuPluggy.

Atualizações de Open Finance não precisam do usuário

Para um item de Open Finance, uma atualização com PATCH /items/{id}API nunca precisa do usuário: ela lê os dados sob o consentimento que o usuário já deu. A exceção é um item que já requer a ação do usuário antes da atualização, que você pode ver no próprio item:

  • status é WAITING_USER_ACTION (o usuário ainda precisa autorizar na instituição), ou executionStatus é USER_AUTHORIZATION_PENDING;
  • executionStatus é USER_AUTHORIZATION_REVOKED (o usuário revogou o consentimento na instituição), USER_AUTHORIZATION_EXPIRED (o consentimento expirou) ou USER_AUTHORIZATION_NOT_GRANTED (o consentimento nunca foi autorizado);
  • consentExpiresAt está no passado: a próxima atualização termina em USER_AUTHORIZATION_EXPIRED.

Nesses casos, o usuário deve passar novamente pela autorização da instituição — veja Consentimentos.

Erros de MFA#

Retornados ao enviar um parâmetro de múltiplos fatores para um Item — veja Atualizando um Item.

codeDescriptionStatusMensagemO que fazer
ITEM_MFA_NOT_FOUND404item não tem solicitação de entrada de mfaO item não está aguardando uma entrada de MFA, então nenhuma pode ser enviada.
ITEM_MFA_ALREADY_PROVIDED400item não tem solicitação de entrada de mfa, já foi fornecidaNada a fazer — o MFA já foi enviado.
ITEM_MFA_EXPIRED400O parâmetro MFA do Item expirou, por favor, inicie uma nova atualizaçãoA janela de MFA fechou. Inicie uma nova atualização para sincronizar a conexão.
ITEM_MFA_PARAMETER_EXPECTED_MISMATCH400O item está esperando o nome do parâmetro MFA ':parameter'O item está aguardando um parâmetro diferente. Use o nome na mensagem.
MFA_PARAMERTER_WAS_ALREADY_USED_ERROR400O parâmetro MFA deve ser atualizado da última execuçãoO valor enviado é o que já foi usado na última execução. Pergunte ao usuário por um novo.
MISSING_MFA_PARAMETER_DATA400Dados do parâmetro MFA ausentesA solicitação não tinha parâmetros de MFA. Envie o parâmetro que o item está aguardando.
MISSING_MFA_PARAMETER_VALUE400Valor do parâmetro MFA ':parameter' ausenteO parâmetro nomeado na mensagem foi enviado vazio. Envie seu valor.

MFA_PARAMERTER_WAS_ALREADY_USED_ERROR

Essa grafia não é um erro de digitação nesta página: a API retorna PARAMERTER. Combine exatamente se você for ramificar sobre isso.

Saldo em tempo real#

Retornado por GET /accounts/{id}/balanceAPI — veja Saldo em Tempo Real. A maioria deles retransmite o que a instituição financeira respondeu.

codeDescriptionStatusMensagemO que fazer
BALANCE_INVALID_REQUEST400A solicitação de saldo foi rejeitada como inválida pela instituição financeira.A instituição rejeitou a solicitação. Tentar a mesma solicitação retorna o mesmo erro; entre em contato com o suporte com o accountId se persistir.
BALANCE_CONSENT_ERROR403A instituição financeira negou acesso ao saldo da conta. O consentimento pode estar expirado ou faltando a permissão necessária.A instituição rejeitou o acesso do consentimento ou negou acesso ao saldo. O consentimento pode estar expirado, revogado ou faltando a permissão necessária; o usuário pode precisar reconectar o item.
BALANCE_NOT_FOUND404O saldo da conta não foi encontrado na instituição financeira.A instituição não tem saldo para esta conta.
BALANCE_OPEN_FINANCE_RATE_LIMIT429A instituição financeira limitou a taxa da solicitação de saldo. Por favor, tente novamente mais tarde.O limite de taxa da instituição para esta conta foi atingido — por exemplo, sua cota mensal de saldo, que é compartilhada com as sincronizações de itens. Tente novamente mais tarde.
BALANCE_FETCH_ERROR500Ocorreu um erro ao buscar o saldo da conta do conectorTente novamente mais tarde.
BALANCE_CONNECTOR_UNAVAILABLE502A instituição financeira está temporariamente indisponível para fornecer o saldo. Por favor, tente novamente mais tarde.A instituição está temporariamente indisponível. Tente novamente mais tarde.
BALANCE_INSTITUTION_RATE_LIMITED503A instituição financeira atingiu seu limite global de solicitações de Open Finance e está temporariamente sem resposta. Por favor, tente novamente mais tarde.O limite cobre todo o tráfego que a instituição recebe, não sua aplicação, então nada está errado com sua solicitação ou o consentimento. Tente novamente mais tarde com um backoff exponencial; nenhum cabeçalho Retry-After é enviado.

Transações#

codeDescriptionStatusMensagemO que fazer
ENDPOINT_DEPRECATED410Este endpoint está obsoleto. Use GET /v2/transactions com paginação por cursor em vez disso.GET /transactions está fechado para aplicações criadas em ou após 2026-06-02 00:00 horário de Brasília (03:00 UTC), e disponível para todos os outros apenas até 2026-12-31. Use GET /v2/transactionsAPI — veja a tabela de migraçãoAPI.

Leia o guia: Códigos de Erros.

Esta página foi útil?