# Códigos de Erro

## Corpo do erro

Todo erro, em qualquer endpoint, tem esta forma:

```json
{
  "code": 404,
  "codeDescription": "ITEM_NOT_FOUND",
  "message": "Item não encontrado"
}
```

| 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 |
| --- | --- | --- |
| `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ção](/reference/authentication) — ou uma solicitação de um IP que não está na lista de IPs permitidos da aplicação (`CLIENT_IP_NOT_ALLOWED`). |
| `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}`](/reference/items/items-update). |
| `429` Too Many Requests | Um limite de taxa foi excedido. | Veja [Limites de Taxa](/reference/rate-limits) 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`.

## Autenticação e acesso

| `codeDescription` | Status | Mensagem | O que fazer |
| --- | --- | --- | --- |
| `CLIENT_IP_NOT_ALLOWED` | `403` | O endereço IP da solicitação não está na lista de IPs permitidos configurados para esta aplicação. | A aplicação tem uma [lista de IPs permitidos](/docs/security/ip-allowlist) e a solicitação veio de outro IP. Aplica-se a `POST /auth` e a cada solicitação feita com a chave da API da aplicação, incluindo `POST /connect_token`; solicitações feitas com um Connect Token não são verificadas. Chame de um IP listado, ou peça a um `OWNER` ou `ADMIN` para adicionar o IP público de saída dos seus servidores no Dashboard. Tentar novamente do mesmo IP retorna o mesmo erro. |

## 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 novamente a mesma solicitação retorna o mesmo erro. |

<Callout variant="warning" title="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.
</Callout>

## Criando e atualizando um Item

Esses retornam de [`POST /items`](/reference/items/items-create) e
[`PATCH /items/{id}`](/reference/items/items-update). 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 — peça suporte se seu caso de uso precisar de um limite 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](https://status.pluggy.ai). |
| `CONNECTOR_REQUIRED_PARAMETER_VALIDATION_ERROR` | `400` | O parâmetro :parameter é necessário para ser renovado para a 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](/docs/guides/meu-pluggy-personal-use). 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](/docs/guides/meu-pluggy-personal-use); 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](/docs/guides/meu-pluggy-personal-use) 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 que "aguardam e tentam novamente" desaparecem ao tentar novamente: o restante 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](#mfa-errors) 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 estiver online novamente. |
| `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 isso 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. |

<Callout variant="info" title="Atualizações de Open Finance não precisam do usuário">
Para um item de Open Finance, uma atualização com [`PATCH /items/{id}`](/reference/items/items-update) **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](/docs/connections/consents).
</Callout>

## Erros de MFA

Retornados ao enviar um parâmetro de múltiplos fatores para um Item — veja
[Atualizando um Item](/docs/connect-widget/updating-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. Peça ao usuário 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 ':parameter' MFA ausente | O parâmetro nomeado na mensagem foi enviado vazio. Envie seu valor. |

<Callout variant="info" title="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.
</Callout>

## Saldo em tempo real

Retornado por [`GET /accounts/{id}/balance`](/reference/account-balance-get) — veja [Saldo em Tempo Real](/docs/products/real-time-balance). 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 novamente 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/transactions`](/reference/transaction/transactions-list-by-cursor) — veja [a tabela de migração](/reference/basic-concepts). |

Leia o guia: [Códigos de Erros](/docs/developer-tools/error-codes).