# Erros e Validações

Aprenda sobre os diferentes status e erros que você pode enfrentar ao usar a API do Pluggy.

Ao conectar um Item, se a conexão for bem-sucedida e todos os produtos forem recuperados corretamente, `GET /items/:id` retornará algo como isto:

```json
{
  "id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
  "status": "UPDATED",
  "executionStatus": "SUCCESS",
  "lastUpdatedAt": "2024-09-27T14:51:46.216Z",
  "error": null,
  "statusDetail": null
}
```

Se o status de execução for `SUCCESS`, isso significa que todos os produtos (contas, transações, etc) foram recuperados corretamente da instituição e estão prontos para serem acessados.

## Item falhou ao fazer login

Ao criar ou atualizar um item, podemos falhar ao fazer login, o que retorna um status `LOGIN_ERROR`:

```json
{
  "id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
  "status": "LOGIN_ERROR",
  "executionStatus": "INVALID_CREDENTIALS",
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Credenciais inválidas."
  },
  "statusDetail": null
}
```

Aqui, nenhum produto foi recuperado, e não podemos tentar a conexão novamente: precisamos que o usuário atualize suas credenciais.

## Item falhou ao começar a recuperar produtos

Existem situações em que não conseguimos recuperar nenhum produto (por exemplo, a instituição está fora do ar, a instituição nos informa que há outra sessão ativa e nos expulsa, etc), mas isso não é necessariamente um problema com o login. Nesses casos, o item terá o status `OUTDATED`:

```json
{
  "id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
  "status": "OUTDATED",
  "executionStatus": "CONNECTION_ERROR",
  "error": {
    "code": "CONNECTION_ERROR",
    "message": "Erro de conectividade, por favor, tente novamente."
  },
  "statusDetail": null
}
```

Quando a instituição está enfrentando uma instabilidade, o `executionStatus` será `SITE_NOT_AVAILABLE`, no entanto, quando é um erro inesperado do nosso lado, o `executionStatus` será `ERROR` ou `CONNECTION_ERROR`.

Você pode tentar atualizar o item novamente para ver se o problema persiste (por exemplo, o banco pode estar instável pela manhã, mas se recuperar mais tarde durante o dia).

Se você tiver auto-sync, itens `OUTDATED` são tentados automaticamente até 5 vezes, com 1 hora entre cada tentativa. Se falhar 5 vezes, ele é removido do auto-sync.

## Item falhou ao recuperar um produto específico

Às vezes, acessamos a instituição corretamente, mas um determinado produto não pode ser recuperado. Isso resultará em um status de `UPDATED` com um status de execução de `PARTIAL_SUCCESS`. O campo `statusDetail` terá informações sobre quais produtos falharam.

```json
{
  "id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
  "status": "UPDATED",
  "executionStatus": "PARTIAL_SUCCESS",
  "error": null,
  "statusDetail": {
    "accounts": {
      "warnings": [],
      "isUpdated": true,
      "lastUpdatedAt": "2024-01-23T22:39:55.622Z"
    },
    "transactions": {
      "warnings": [],
      "isUpdated": false,
      "lastUpdatedAt": "2024-01-21T22:39:55.622Z"
    },
    "creditCards": null
  }
}
```

Você também pode tentar novamente nesses casos para ver se o problema persiste. O auto-sync não tenta novamente `PARTIAL_SUCCESS`.

> **Entendendo Avisos**
>
> Quando produtos falham ou têm problemas, o `statusDetail` inclui avisos que explicam o porquê. Aprenda mais sobre avisos e como lidar com eles no guia [Warnings & Status Codes](/docs/warnings-status-codes).

## O objeto de erro

O seguinte tipo representa a estrutura completa do erro:

```typescript
type ExecutionErrorResult = {
  code: ExecutionErrorCodes
  message: string
  providerMessage?: string
  attributes?: Record<string, string>
}
```

Com certos erros, o objeto de erro é retornado com uma chave `attributes` com informações adicionais necessárias para futuras execuções:

```json
{
  "error": {
    "code": "USER_AUTHORIZATION_PENDING",
    "message": "O usuário precisa conceder as permissões necessárias para sua conta.",
    "attributes": {
      "deviceNickname": "123456789"
    }
  }
}
```

Quando o código de erro é `ACCOUNT_NEEDS_ACTION`, usamos um campo chamado `providerMessage` em português, com qualquer mensagem de alerta relevante da instituição:

```json
{
  "error": {
    "code": "ACCOUNT_NEEDS_ACTION",
    "message": "A conta precisa de uma ação manual do usuário.",
    "providerMessage": "Sua senha deve ser alterada"
  }
}
```

O campo `providerMessage` é a mensagem exata retornada pela Instituição Financeira ao encontrar um erro, sem qualquer tratamento. Dessa forma, o usuário pode ter uma mensagem amigável e clara sobre o porquê isso está acontecendo. Não fornecemos uma lista dessas mensagens, pois estão sujeitas a alterações pela FI.

## Tratando erros

A lógica de tratamento de erros, em geral, pode parecer algo assim:

- **Se `executionStatus` for `SUCCESS`**
  - Busque todos os produtos (transações, contas, etc)
  - Verifique os avisos (se houver) para ver informações sobre como os dados podem ser melhorados.
- **Se `executionStatus` for `PARTIAL_SUCCESS`**
  - Busque todos os produtos `isUpdated: true`
  - Gere um alerta interno se for um produto crítico (por exemplo, `TRANSACTIONS`) ou adicione um alerta para o usuário.
  - Verifique os avisos (se houver) para ver informações sobre por que o produto falhou.
- **Se o status for `LOGIN_ERROR`** (Open Finance não requer tratamento desse caso):
  - Não busque nenhum produto
  - Solicite ao usuário que insira suas credenciais novamente
- **Se o status for `OUTDATED`**:
  - Não busque nenhum produto
  - Gere um alerta interno ou adicione um alerta para o usuário

Para conectores diretos, todos os casos de erro estão descritos [aqui](/docs/item-lifecycle#error-states).

### Casos de erro do Open Finance

Para o Open Finance, há apenas um subconjunto de possíveis casos de erro, conforme segue, dividido por status e `executionStatus`:

- **`LOGIN_ERROR`**:
  - `INVALID_CREDENTIALS`: o CPF/CNPJ é inválido
  - `USER_AUTHORIZATION_NOT_GRANTED`: o usuário rejeitou o consentimento durante o fluxo de autorização
  - `USER_AUTHORIZATION_REVOKED`: o usuário revogou o consentimento de seu banco
- **`OUTDATED`**:
  - `USER_INPUT_TIMEOUT`: o usuário nunca terminou o fluxo de autorização
  - `SITE_NOT_AVAILABLE`: a instituição está atualmente instável
  - `ERROR`/`CONNECTION_ERROR`: ocorreu um erro inesperado ao acessar a instituição
- **`UPDATED`**:
  - `PARTIAL_SUCCESS`: falha ao recuperar um produto, provavelmente porque o limite mensal foi atingido ou porque a instituição tem uma instabilidade temporária nesse produto.

Um produto também pode falhar porque a instituição não respondeu dentro do **timeout de 15 segundos** da rede. Veja [Tempo de resposta e timeout](/docs/open-finance/rate-limits#response-time-and-timeout) para como esse limite funciona e como difere da meta de desempenho da rede (P95).

## Validações de Criação de Item

As validações na API do Pluggy são muito importantes. Elas são usadas para evitar a execução de conectores com parâmetros inválidos e para criar conexões de item que não serão sincronizadas devido a credenciais ou parâmetros inválidos. Ao criar ou atualizar um item, as validações serão executadas para esse item com base nas credenciais do conector.

Este é um exemplo de uma resposta de validação ao criar um item:

```json
// HTTP 400
{
  "message": "Os parâmetros do conector não correspondem às regras de validação",
  "errors": [
    {
      "code": "002",
      "message": "o comprimento do parâmetro usuário deve ser de pelo menos 6.",
      "parameter": "user"
    },
    {
      "code": "002",
      "message": "o comprimento do parâmetro senha deve ser de pelo menos 6.",
      "parameter": "password"
    }
  ]
}
```

## Erros de rejeição de atualização

Existem alguns casos em que um item não pôde ser atualizado devido ao estado do item:

| Código | Código de Erro | Descrição | Ação |
|---|---|---|---|
| 409 | `ITEM_IS_ALREADY_UPDATING` | O item já está sendo atualizado | Aguarde o item terminar a sincronização existente. |
| 409 | `ITEM_CREATION_LIMIT_EXCEEDED` | Não é permitido atualizar o item porque ele foi atualizado antes da frequência mínima do cliente | Aguarde até que o atraso contratado tenha ocorrido. |
| 409 | `CLIENT_HAS_ITEM_UPDATES_DISABLED` | O cliente não pode acionar atualizações manuais, pois foi desativado pelo Pluggy | Entre em contato com a equipe de suporte para entender por que o cliente foi desativado para atualizações. |
| 400 | `ITEM_ORIGINAL_CONNECTED_WITH_DIFFERENT_ACCOUNT` | O item foi originalmente conectado com uma conta diferente, por favor, use a conta original | O usuário inicialmente se conectou com uma empresa/conta diferente, não pode alterar a configuração de conexão. |