Corpo do erro#
Cada erro, em cada endpoint, tem esta forma:
| Campo | Significado |
|---|---|
code | O status HTTP, repetido. Sempre presente. |
message | Uma frase para uma pessoa. Sempre presente; não estável. |
codeDescription | Um identificador estável para o erro específico, quando o endpoint distingue vários. Baseie-se nisso, não em message. |
data | Detalhe extra para alguns erros — por exemplo, os Itens que já existem ao criar um que duplicaria uma conexão. |
Códigos de status#
| Status | Significado | Geralmente por causa de |
|---|---|---|
400 Bad Request | A solicitação é inválida. | Um campo ausente ou malformado (INVALID_PARAMETERS). |
401 Unauthorized | A 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 Forbidden | A credencial não pode acessar este recurso. | Um Connect Token usado fora de seu escopo — veja AutenticaçãoAPI. |
404 Not Found | Nenhum recurso desse tipo. | Um id que não existe. |
405 Method Not Allowed | O endpoint não suporta este verbo. | |
406 Not Acceptable | Um formato diferente de JSON foi solicitado. | |
409 Conflict | A solicitação contradiz o estado atual do recurso. | Um conflito ao atualizar um Item — veja PATCH /items/{id}API. |
429 Too Many Requests | Um limite de taxa foi excedido. | Veja Limites de TaxaAPI para os limites e o cabeçalho Retry-After. |
500 Internal Server Error | Algo falhou do nosso lado. | Tente novamente mais tarde. |
503 Service Unavailable | Temporariamente 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#
codeDescription | Status | Mensagem | O que fazer |
|---|---|---|---|
INVALID_PARAMETERS | 400 | Nomeia 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.
codeDescription | Status | Mensagem | O que fazer |
|---|---|---|---|
PARAMETERS_NOT_PROVIDED | 400 | parâmetros não foram fornecidos | Envie as credenciais da conexão para sincronizar o item. |
ITEM_ALREADY_UPDATING | 400 | Uma atualização já está em andamento, aguarde até que a última execução termine | Este item está sincronizando. Aguarde a execução terminar — sucesso ou erro — antes de acionar outra. |
ITEM_IS_ALREADY_UPDATING | 400 | Há um item ativo para o conjunto de credenciais que não terminou de executar | O 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_FREQUENCY | 409 | Atualizações do cliente neste item são permitidas no máximo a cada :minUpdateFrequencyAllowedInHours horas. A última atualização foi em :lastUpdatedAt | Aguarde 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_ERROR | 400 | A última execução teve um erro de login, você deve atualizar os parâmetros | A última sincronização falhou ao fazer login. Envie novas credenciais antes de atualizar novamente. |
TOO_MANY_CONSECUTIVE_LOGIN_FAILURES | 400 | deve 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_ERRORS | 400 | Houve mais de 5 sincronizações falhadas, entre em contato com o suporte | A conexão falhou muitas vezes seguidas. Relate ao suporte com o itemId. |
ITEM_IN_ERROR_COOLDOWN | 409 | Este conjunto de credenciais falhou recentemente ao conectar e está em um período de cooldown, por favor, tente novamente mais tarde | Essas credenciais falharam recentemente e estão em um cooldown. Tente novamente após passar. |
CONNECTOR_OFFLINE | 409 | este conector está offline neste momento | O conector não está aceitando execuções agora. Tente novamente mais tarde — veja status.pluggy.ai. |
CONNECTOR_REQUIRED_PARAMETER_VALIDATION_ERROR | 400 | O 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_ACCOUNT | 409 | O Item foi originalmente conectado com uma conta diferente, por favor, use a conta original | As 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_EXCEEDED | 409 | O 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_DISABLED | 409 | O cliente tem atualizações de itens desativadas | Atualizações foram desativadas para a equipe. Entre em contato com o suporte. |
CREATE_ITEMS_API_FREE_DISABLED | 400 | A assinatura gratuita só pode criar itens através do nosso Connect Widget | Na assinatura gratuita, itens são criados através do Connect Widget. |
SANDBOX_CLIENT_ITEM_UPDATE_NOT_ALLOWED | 400 | O 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_ALLOWED | 400 | Clientes 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_ALLOWED | 400 | A assinatura atual do cliente não permite conectar contas reais, apenas itens do Sandbox (Pluggy Bank) e Meu Pluggy | Sua 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_ALLOWED | 400 | O item MeuPluggy não pode ser atualizado | Itens 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.
codeDescription | Requer o usuário | Quem age |
|---|---|---|
PARAMETERS_NOT_PROVIDED | Sim | O usuário — insere as credenciais da conexão. |
LAST_EXECUTION_HAD_LOGIN_ERROR | Sim | O usuário — insere novas credenciais. |
CONNECTOR_REQUIRED_PARAMETER_VALIDATION_ERROR | Sim | O usuário — fornece o parâmetro nomeado na mensagem novamente. |
ITEM_ORIGINAL_CONNECTED_WITH_DIFFERENT_ACCOUNT | Sim | O usuário — reconecta com a conta original ou cria um novo item. |
ITEM_MFA_EXPIRED | Sim | O usuário — inicia uma nova atualização e insere um novo valor de MFA. |
MFA_PARAMERTER_WAS_ALREADY_USED_ERROR | Sim | O usuário — insere um novo valor de MFA. |
ITEM_ALREADY_UPDATING | Não | Ninguém — aguarde a execução em andamento e tente novamente. |
ITEM_IS_ALREADY_UPDATING | Não | Ninguém — aguarde a execução do outro item e tente novamente. |
CLIENT_IS_UPDATING_BEFORE_ALLOWED_FREQUENCY | Não | Ninguém — aguarde a frequência mínima e tente novamente. |
TOO_MANY_CONSECUTIVE_LOGIN_FAILURES | Não | Ninguém — aguarde o cooldown na mensagem e tente novamente. |
ITEM_IN_ERROR_COOLDOWN | Não | Ninguém — aguarde o cooldown e tente novamente. |
CONNECTOR_OFFLINE | Não | Ninguém — tente novamente quando o conector voltar online. |
ITEM_MFA_PARAMETER_EXPECTED_MISMATCH | Não | Sua integração — envie o valor sob o nome do parâmetro na mensagem. |
ITEM_MFA_NOT_FOUND | Não | Sua integração — envie MFA apenas enquanto o item estiver aguardando por isso. |
ITEM_MFA_ALREADY_PROVIDED | Não | Sua integração — nada a enviar; o MFA já foi recebido. |
MISSING_MFA_PARAMETER_DATA | Não | Sua integração — a solicitação não tinha parâmetros de MFA; envie-os. |
MISSING_MFA_PARAMETER_VALUE | Não | Sua 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_ERRORS | Não | Suporte Pluggy — relate com o itemId. |
ITEM_CREATION_LIMIT_EXCEEDED | Não | Sua assinatura — exclua itens não utilizados ou entre em contato com o suporte. |
CLIENT_HAS_ITEM_UPDATES_DISABLED | Não | Suporte Pluggy. |
CREATE_ITEMS_API_FREE_DISABLED | Não | Sua assinatura — crie itens através do Connect Widget ou atualize. |
SANDBOX_CLIENT_ITEM_UPDATE_NOT_ALLOWED | Não | Sua assinatura. |
TRIAL_CLIENT_ITEM_CREATE_NOT_ALLOWED | Não | Sua assinatura — use conectores do Sandbox durante o teste ou atualize. |
CLIENT_PLAN_REAL_CONNECTORS_NOT_ALLOWED | Não | Sua assinatura — use conectores do Sandbox ou MeuPluggy, ou atualize. |
MEU_PLUGGY_ITEM_UPDATE_NOT_ALLOWED | Não | Sua 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), ouexecutionStatuséUSER_AUTHORIZATION_PENDING;executionStatuséUSER_AUTHORIZATION_REVOKED(o usuário revogou o consentimento na instituição),USER_AUTHORIZATION_EXPIRED(o consentimento expirou) ouUSER_AUTHORIZATION_NOT_GRANTED(o consentimento nunca foi autorizado);consentExpiresAtestá no passado: a próxima atualização termina emUSER_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.
codeDescription | Status | Mensagem | O que fazer |
|---|---|---|---|
ITEM_MFA_NOT_FOUND | 404 | item não tem solicitação de entrada de mfa | O item não está aguardando uma entrada de MFA, então nenhuma pode ser enviada. |
ITEM_MFA_ALREADY_PROVIDED | 400 | item não tem solicitação de entrada de mfa, já foi fornecida | Nada a fazer — o MFA já foi enviado. |
ITEM_MFA_EXPIRED | 400 | O parâmetro MFA do Item expirou, por favor, inicie uma nova atualização | A janela de MFA fechou. Inicie uma nova atualização para sincronizar a conexão. |
ITEM_MFA_PARAMETER_EXPECTED_MISMATCH | 400 | O 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_ERROR | 400 | O parâmetro MFA deve ser atualizado da última execução | O valor enviado é o que já foi usado na última execução. Pergunte ao usuário por um novo. |
MISSING_MFA_PARAMETER_DATA | 400 | Dados do parâmetro MFA ausentes | A solicitação não tinha parâmetros de MFA. Envie o parâmetro que o item está aguardando. |
MISSING_MFA_PARAMETER_VALUE | 400 | Valor do parâmetro MFA ':parameter' ausente | O 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.
codeDescription | Status | Mensagem | O que fazer |
|---|---|---|---|
BALANCE_INVALID_REQUEST | 400 | A 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_ERROR | 403 | A 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_FOUND | 404 | O 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_LIMIT | 429 | A 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_ERROR | 500 | Ocorreu um erro ao buscar o saldo da conta do conector | Tente novamente mais tarde. |
BALANCE_CONNECTOR_UNAVAILABLE | 502 | A 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_LIMITED | 503 | A 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#
codeDescription | Status | Mensagem | O que fazer |
|---|---|---|---|
ENDPOINT_DEPRECATED | 410 | Este 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.
