# Avisos e Códigos de Status

Entendendo os códigos de aviso e seus significados ao recuperar dados dos conectores Pluggy.

## Visão Geral

Ao recuperar dados de instituições financeiras através do Pluggy, você pode encontrar situações em que alguns dados estão indisponíveis ou não podem ser recuperados por várias razões. O Pluggy utiliza um sistema de aviso padronizado para informá-lo sobre essas situações sem falhar em todo o processo de coleta de dados.

Os avisos são retornados como parte do `statusDetail` para cada tipo de produto (Contas, Cartões de Crédito, Transações, etc.) e incluem:

- Um **código**: Um identificador único para o tipo de aviso
- Uma **mensagem**: Uma descrição legível por humanos do problema
- Uma **providerMessage** (opcional): A mensagem exata da Instituição Financeira em português, sem tratamento

Isso permite que você lide com essas situações de forma elegante em sua aplicação e forneça feedback apropriado aos seus usuários.

> **Diferença entre Erros e Avisos**
>
> Erros indicam que toda a solicitação falhou e nenhum dado foi recuperado (veja [Erros & Validações](/docs/errors-validations)). Avisos indicam que a solicitação foi bem-sucedida, mas alguns dados podem estar incompletos ou indisponíveis. Sua aplicação deve lidar com ambos os cenários de forma apropriada.

## Quando os Avisos Ocorrem

Os avisos estão incluídos no `statusDetail` nesses cenários:

- O produto não pôde ser recuperado, e contém o motivo (`isUpdated: false`)
- O produto foi recuperado corretamente, mas pode ser melhorado com alguma ação do usuário (`isUpdated: true`)

Por exemplo: se o usuário não tem acesso a transações, nós as retornamos como vazias, mas um aviso sobre transações informa que, com mais permissões, poderíamos estar recuperando transações.

### Cenários Comuns

#### Problemas de Permissão

O usuário não concedeu as permissões necessárias durante o fluxo de consentimento, ou o consentimento expirou.

#### Status do Recurso

Um recurso específico (conta, cartão de crédito ou empréstimo) está em um estado que impede a recuperação de dados:

- **Autorização Pendente**: O recurso está aguardando autorização do usuário na instituição financeira
- **Indisponível Temporariamente**: O recurso está temporariamente indisponível (por exemplo, manutenção)
- **Indisponível**: O recurso está permanentemente indisponível

#### Limites de Taxa

A instituição financeira atingiu seu limite de taxa operacional para o período atual. Veja [Limites de Taxa Operacional](/docs/rate-limits-of) para mais informações sobre limites de taxa do Open Finance.

#### Problemas de Sincronização

Alguns dados não puderam ser sincronizados, mas dados de fallback de uma sincronização bem-sucedida anterior estão sendo usados em vez disso.

## Lidando com Avisos

Os avisos estão incluídos na resposta para cada produto. Aqui está um exemplo de como os avisos aparecem na resposta da API:

**Conectores OF**

```json title="Conectores OF"
{
  "accounts": [],
  "warnings": {
    "accounts": [
      {
        "code": "ACCT_002",
        "message": "A conta c0a7d38c-d967-3b94-9d0b-c391068f4b20 está pendente de autorização"
      }
    ],
    "creditCards": [],
    "transactions": [],
    "loans": []
  }
}
```

**Conectores Diretos**

```json title="Conectores Diretos"
{
  "accounts": [],
  "warnings": {
    "investments": [
      {
        "code": "001",
        "message": "O usuário não tem permissões para visualizar investimentos nesta conta",
        "providerMessage": "Seu perfil de usuário não está habilitado para esta transação."
      }
    ],
    "creditCards": [],
    "transactions": [],
    "loans": []
  }
}
```

Neste exemplo, uma conta está pendente de autorização e não foi incluída na lista de contas.

## Referência de Códigos de Aviso

### Conectores de Open Finance

Os conectores de Open Finance utilizam um sistema de aviso padronizado e tipado com códigos específicos por produto.

#### Contas (ACCOUNTS)

| Código | Motivo | Descrição |
|---|---|---|
| `ACCT_001` | Permissão ausente | O usuário não concedeu permissão para coletar contas (`ACCOUNTS_ALL`) |
| `ACCT_002` | Autorização pendente | A conta está pendente de autorização na instituição financeira |
| `ACCT_003` | Indisponível temporariamente | A conta está temporariamente indisponível |
| `ACCT_004` | Indisponível | A conta está indisponível |
| `ACCT_005` | Permissão de limites de cheque ausente | O usuário não concedeu permissão para coletar limites de cheque das contas (`ACCOUNTS_LIMITS`) |
| `ACCT_006` | Limite rígido de contas | Existem mais de 260 contas correntes para recuperar, mas retornamos apenas até esse número |

#### Cartões de Crédito (CREDIT_CARDS)

| Código | Motivo | Descrição |
|---|---|---|
| `CC_001` | Permissão ausente | O usuário não concedeu permissão para coletar cartões de crédito (`CREDIT_CARDS_ALL`) |
| `CC_002` | Autorização pendente | O Cartão de Crédito está pendente de autorização na instituição financeira |
| `CC_003` | Indisponível temporariamente | O Cartão de Crédito está temporariamente indisponível |
| `CC_004` | Indisponível | O Cartão de Crédito está indisponível |
| `CC_005` | Permissão de faturas ausente | O usuário não concedeu permissão para coletar faturas de cartões de crédito (`CREDIT_CARDS_BILLS`) |
| `CC_006` | Permissão de transações ausente | O usuário não concedeu permissão para coletar transações de cartões de crédito (`CREDIT_CARDS_TRANSACTIONS`) |
| `CC_007` | Limites ausentes | A instituição não retorna limite para este cartão de crédito |

#### Transações (TRANSACTIONS)

| Código | Motivo | Descrição |
|---|---|---|
| `TXN_001` | Permissão ausente | O usuário não concedeu permissão para coletar transações de contas (`ACCOUNTS_ALL` ou `ACCOUNTS_TRANSACTIONS`) |
| `TXN_002` | Nenhuma conta disponível | Nenhuma conta disponível para buscar transações |
| `TXN_003` | Limite de taxa atingido | Etapa de transações pulada devido a erro de limite de taxa na etapa de contas e nenhuma conta disponível |
| `TXN_004` | Sem permissão para coletar contas | O usuário não concedeu permissão para coletar contas, etapa de transações pulada |
| `TXN_005` | A etapa de contas teve erros | Etapa de transações pulada devido a erros na etapa de contas |
| `TXN_006` | Limite de taxa atingido | Erro de limite de taxa na etapa de contas, mas prosseguindo com transações usando contas disponíveis |

#### Empréstimos (LOANS)

| Código | Motivo | Descrição |
|---|---|---|
| `LOAN_001` | Permissão ausente | O usuário não concedeu permissão para coletar empréstimos (`CREDIT_OPERATIONS_ALL`) |
| `LOAN_002` | Autorização pendente | O Empréstimo está pendente de autorização na instituição financeira |
| `LOAN_003` | Indisponível temporariamente | O Empréstimo está temporariamente indisponível |
| `LOAN_004` | Indisponível | O Empréstimo está indisponível |
| `LOAN_005` | Falha na sincronização de parcelas | Falha ao sincronizar Parcelas do Empréstimo, usando dados de fallback da sincronização anterior |
| `LOAN_006` | Falha na sincronização de pagamentos | Falha ao sincronizar Pagamentos do Empréstimo, usando dados de fallback da sincronização anterior |

#### Investimentos (INVESTMENTS)

| Código | Motivo | Descrição |
|---|---|---|
| `INV_001` | Permissão ausente | O usuário não concedeu permissão para coletar investimentos (`INVESTMENTS_ALL`) |
| `INV_002` | Permissão não concedida | A permissão do produto de investimento não foi concedida |
| `INV_003` | Não suportado pela FI | Produto de investimento não suportado pela instituição financeira |
| `INV_004` | Limite de taxa atingido | Limite mensal de Open Finance atingido |
| `INV_005` | Tipo de produto não suportado | Tipo específico de produto de investimento não suportado pela instituição financeira |

#### Identidade (IDENTITY)

| Código | Motivo | Descrição |
|---|---|---|
| `ID_001` | Permissão ausente | O usuário não concedeu permissão para coletar identidade (`REGISTRATION_ALL`) |
| `ID_002` | Permissão de subproduto não concedida | A permissão de subproduto de identidade específica não foi concedida |
| `ID_003` | Limite de taxa de subproduto atingido | O limite de taxa de subproduto de identidade específico foi atingido |
| `ID_004` | Erro conhecido | Erro 400 conhecido para subproduto de identidade específico |

### Conectores Diretos

Os conectores diretos podem usar códigos genéricos (como `001`, `002`, `003`) com significados específicos do conector. O campo `providerMessage` fornece contexto em português da instituição.

Aqui está uma lista de avisos conhecidos para Conectores Diretos:

| Conector + Produto | Código | Mensagem | Mensagem do Provedor (PT-BR) | Item de Ação |
|---|---|---|---|---|
| Itaú PJ PAYMENT_DATA | `001` | O usuário não tem permissão para obter dados de pagamento do código QR PIX recebido | Consulte seu gerente ou Central de Atendimento para liberar permissões | Contatar gerente para conceder permissões de PIX |
| Itaú PJ PAYMENT_DATA | `001` | O cliente não tem permissões para ver dados de pagamento PIX | Cliente não tem permissão para acesso a PIX | Conceder acesso do usuário à seção PIX |
| Itaú PJ INVESTMENTS | `001` | O usuário não tem permissões para visualizar investimentos | Seu perfil de usuário não está habilitado para esta transação | Conceder acesso do usuário à seção de investimentos |
| Itaú PJ CREDIT_CARDS | `001` | O usuário não tem acesso aos resumos de cartões de crédito | - | Conceder acesso à seção de cartões de crédito |
| Santander PJ ACCOUNTS | `001` | O operador não tem acesso às Contas | - | Permitir que o operador acesse a seção de contas |
| Santander PJ ACCOUNTS | `002` | O usuário não tem acesso ao 'Extrato 365 dias' | - | Informações recuperadas de 'Saldo e Extrato' em vez disso |
| Santander PJ CREDIT_CARDS | `001` | O usuário não tem permissões, não pode recuperar cartões de crédito | - | Permitir que o operador acesse a seção de cartões de crédito |
| Santander PJ TRANSACTIONS | `003` | O usuário não tem acesso ao 'Extrato 365 dias' ou está offline | - | Permitir acesso ao 'Extrato 365' para remover limitações de dados |
| Bradesco PJ PAYMENT_DATA | `001` | O usuário não tem permissões para obter pagamentos TED / PIX / TEF | - | - |
| Bradesco PJ INVESTMENTS | `001` | O usuário não tem acesso a fundos mútuos / investimentos de renda fixa | Solicite ao usuário máster para ter acesso a esse serviço | Solicitar ao usuário máster para conceder acesso |
| Bradesco PJ INVESTMENTS_TRANSACTIONS | `001` | O usuário não tem acesso às informações de transações de investimentos | Solicite ao usuário máster para ter acesso a esse serviço | Solicitar ao usuário máster para conceder acesso |
| Bradesco PJ INVESTMENTS_TRANSACTIONS | `001` | O usuário não tem permissões para visualizar transações de renda fixa / fundos mútuos | - | - |
| Bradesco PJ TRANSACTIONS | `001` | Transações não estão habilitadas para esta conta | Solicite ao usuário máster para ter acesso a esse serviço | Solicitar ao usuário máster para conceder acesso |
| Caixa PJ TRANSACTIONS | `001` | Situação impeditiva para movimentar sua conta | Situação impeditiva para movimentar sua conta. Procure sua agência para regularizar | Contatar a agência para regularizar |
| XP INVESTMENTS | `001` | O usuário não tem permissões para acessar ativos do Tesouro | A Conta não está habilitada para operar no Tesouro Direto pois já existe outra conta XP Inc atrelada ao CPF do cliente. Caso queira trocar a conta habilitada, entre em contato com a XP | O usuário deve conceder acesso ao Tesouro Direto |
| Sicoob PJ ACCOUNTS | `001` | O usuário não tem permissões para obter contas | Usuário não tem permissão para executar a transação - Consultas - Saldo de conta corrente | Permitir acesso do usuário através do aplicativo móvel à seção de saldo da conta |

> **Mensagens do Provedor**
>
> O campo `providerMessage` contém a mensagem exata da Instituição Financeira em português, sem nenhum tratamento. Dessa forma, o usuário pode ter uma mensagem amigável e clara do motivo pelo qual isso está acontecendo. Não fornecemos uma lista completa dessas mensagens, pois estão sujeitas a alterações pela FI.