# Códigos de Erro

## Corpo do erro

Todo erro, em todo 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 Items 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. |
| `401` Unauthorized | A credencial está ausente, errada ou expirada. | Uma API Key que passou de 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). |
| `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 offline para manutenção. | 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`.

## 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 — 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](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. 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, os itens são criados através do Connect Widget. |
| `SANDBOX_CLIENT_ITEM_UPDATE_NOT_ALLOWED` | `400` | O nível de assinatura do cliente atual só pode atualizar itens do Sandbox (Pluggy Bank) | Seu nível de assinatura só permite atualizar itens do Sandbox (Pluggy Bank). |

## 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 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 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. |

<Callout variant="info" title="MFA_PARAMERTER_WAS_ALREADY_USED_ERROR">
A grafia não é um erro de digitação nesta página: a API retorna `PARAMERTER`. Combine exatamente se você ramificar sobre isso.
</Callout>

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