# Warnings & Status Codes

Understanding warning codes and their meanings when retrieving data from Pluggy connectors.

## Overview

When retrieving data from financial institutions through Pluggy, you may encounter situations where some data is unavailable or cannot be retrieved due to various reasons. Pluggy uses a standardized warning system to inform you about these situations without failing the entire data collection process.

Warnings are returned as part of the `statusDetail` for each product type (Accounts, Credit Cards, Transactions, etc.) and include:

- A **code**: A unique identifier for the warning type
- A **message**: A human-readable description of the issue
- A **providerMessage** (optional): The exact message from the Financial Institution in Portuguese, without treatment

This allows you to handle these situations gracefully in your application and provide appropriate feedback to your users.

> **Difference between Errors and Warnings**
>
> Errors indicate that the entire request failed and no data was retrieved (see [Errors & Validations](/docs/errors-validations)). Warnings indicate that the request succeeded but some data may be incomplete or unavailable. Your application should handle both scenarios appropriately.

## When Warnings Occur

Warnings are included in the `statusDetail` on these scenarios:

- The product failed to be retrieved, and it contains the reason (`isUpdated: false`)
- The product was retrieved correctly, but it can be improved with some user action (`isUpdated: true`)

For instance: if the user doesn't have access to transactions, we return them as empty, but a warning on transactions informs that, with more permissions, we could be retrieving transactions.

### Common Scenarios

#### Permission Issues

The user hasn't granted the necessary permissions during the consent flow, or the consent has expired.

#### Resource Status

A specific resource (account, credit card, or loan) is in a state that prevents data retrieval:

- **Pending Authorization**: The resource is awaiting user authorization at the financial institution
- **Temporarily Unavailable**: The resource is temporarily unavailable (e.g., maintenance)
- **Unavailable**: The resource is permanently unavailable

#### Rate Limits

The financial institution has reached its operational rate limit for the current period. See [Operational Rate Limits](/docs/rate-limits-of) for more information about Open Finance rate limits.

#### Sync Issues

Some data could not be synchronized, but fallback data from a previous successful sync is being used instead.

## Handling Warnings

Warnings are included in the response for each product. Here's an example of how warnings appear in the API response:

**OF Connectors**

```json title="OF Connectors"
{
  "accounts": [],
  "warnings": {
    "accounts": [
      {
        "code": "ACCT_002",
        "message": "Account c0a7d38c-d967-3b94-9d0b-c391068f4b20 is pending authorization"
      }
    ],
    "creditCards": [],
    "transactions": [],
    "loans": []
  }
}
```

**Direct Connectors**

```json title="Direct Connectors"
{
  "accounts": [],
  "warnings": {
    "investments": [
      {
        "code": "001",
        "message": "User lacks permissions to view investments on this account",
        "providerMessage": "Seu perfil de usuário não está habilitado para esta transação."
      }
    ],
    "creditCards": [],
    "transactions": [],
    "loans": []
  }
}
```

In this example, one account is pending authorization and wasn't included in the accounts list.

## Warning Codes Reference

### Open Finance Connectors

Open Finance connectors use a standardized, typed warning system with specific codes per product.

#### Accounts (ACCOUNTS)

| Code | Reason | Description |
|---|---|---|
| `ACCT_001` | Missing permission | User hasn't granted permission to collect accounts (`ACCOUNTS_ALL`) |
| `ACCT_002` | Pending authorization | Account is pending authorization at the financial institution |
| `ACCT_003` | Temporarily unavailable | Account is temporarily unavailable |
| `ACCT_004` | Unavailable | Account is unavailable |
| `ACCT_005` | Missing overdraft limits permission | User hasn't granted permission to collect accounts overdraft limits (`ACCOUNTS_LIMITS`) |
| `ACCT_006` | Accounts hard limit | There are more than 260 checking accounts to retrieve but we only return until this number |

#### Credit Cards (CREDIT_CARDS)

| Code | Reason | Description |
|---|---|---|
| `CC_001` | Missing permission | User hasn't granted permission to collect credit cards (`CREDIT_CARDS_ALL`) |
| `CC_002` | Pending authorization | Credit Card is pending authorization at the financial institution |
| `CC_003` | Temporarily unavailable | Credit Card is temporarily unavailable |
| `CC_004` | Unavailable | Credit Card is unavailable |
| `CC_005` | Missing bills permission | User hasn't granted permission to collect credit card bills (`CREDIT_CARDS_BILLS`) |
| `CC_006` | Missing transactions permission | User hasn't granted permission to collect credit card transactions (`CREDIT_CARDS_TRANSACTIONS`) |
| `CC_007` | Missing limits | Institution does not return limit for this credit card |

#### Transactions (TRANSACTIONS)

| Code | Reason | Description |
|---|---|---|
| `TXN_001` | Missing permission | User hasn't granted permission to collect accounts transactions (`ACCOUNTS_ALL` or `ACCOUNTS_TRANSACTIONS`) |
| `TXN_002` | No accounts available | No accounts available to fetch transactions for |
| `TXN_003` | Rate limit reached | Transactions step skipped due to rate limit error in accounts step and no accounts available |
| `TXN_004` | No permission to collect accounts | User hasn't granted permission to collect accounts, transactions step skipped |
| `TXN_005` | Accounts step had errors | Transactions step skipped due to errors in accounts step |
| `TXN_006` | Rate limit reached | Rate limit error in accounts step, but proceeding with transactions using available accounts |

#### Loans (LOANS)

| Code | Reason | Description |
|---|---|---|
| `LOAN_001` | Missing permission | User hasn't granted permission to collect loans (`CREDIT_OPERATIONS_ALL`) |
| `LOAN_002` | Pending authorization | Loan is pending authorization at the financial institution |
| `LOAN_003` | Temporarily unavailable | Loan is temporarily unavailable |
| `LOAN_004` | Unavailable | Loan is unavailable |
| `LOAN_005` | Installments sync failed | Failed to sync Loan Installments, using fallback data from previous sync |
| `LOAN_006` | Payments sync failed | Failed to sync Loan Payments, using fallback data from previous sync |

#### Investments (INVESTMENTS)

| Code | Reason | Description |
|---|---|---|
| `INV_001` | Missing permission | User hasn't granted permission to collect investments (`INVESTMENTS_ALL`) |
| `INV_002` | Permission not granted | Investment product permission has not been granted |
| `INV_003` | Not supported by FI | Investment product not supported by the financial institution |
| `INV_004` | Rate limit reached | Open Finance monthly rate limit reached |
| `INV_005` | Product type not supported | Specific investment product type not supported by the financial institution |

#### Identity (IDENTITY)

| Code | Reason | Description |
|---|---|---|
| `ID_001` | Missing permission | User hasn't granted permission to collect identity (`REGISTRATION_ALL`) |
| `ID_002` | Subproduct permission not granted | Specific identity subproduct permission has not been granted |
| `ID_003` | Subproduct rate limit reached | Specific identity subproduct rate limit has been reached |
| `ID_004` | Known error | Known 400 error for specific identity subproduct |

### Direct Connectors

Direct connectors may use generic codes (like `001`, `002`, `003`) with connector-specific meanings. The `providerMessage` field provides context in Portuguese from the institution.

Here is a list of known warnings for Direct Connectors:

| Connector + Product | Code | Message | Provider Message (PT-BR) | Action Item |
|---|---|---|---|---|
| Itaú PJ PAYMENT_DATA | `001` | User doesn't have permission to obtain received PIX QR code payment data | Consulte seu gerente ou Central de Atendimento para liberar permissões | Contact manager to grant PIX permissions |
| Itaú PJ PAYMENT_DATA | `001` | Client does not have permissions to see PIX payment data | Cliente não tem permissão para acesso a PIX | Grant user access to PIX section |
| Itaú PJ INVESTMENTS | `001` | User doesn't have permissions to view investments | Seu perfil de usuário não está habilitado para esta transação | Grant user access to investments section |
| Itaú PJ CREDIT_CARDS | `001` | User doesn't have access to credit cards resumes | - | Grant access to credit cards section |
| Santander PJ ACCOUNTS | `001` | Operator doesn't have access to Accounts | - | Allow operator to access the accounts section |
| Santander PJ ACCOUNTS | `002` | User doesn't have access to 'Extrato 365 dias' | - | Information retrieved from 'Saldo e Extrato' instead |
| Santander PJ CREDIT_CARDS | `001` | User doesn't have permissions, cannot recover credit cards | - | Allow operator to access credit cards section |
| Santander PJ TRANSACTIONS | `003` | User doesn't have access to 'Extrato 365 dias' or it's offline | - | Allow access to 'Extrato 365' to remove data limitations |
| Bradesco PJ PAYMENT_DATA | `001` | User doesn't have permissions to obtain TED / PIX / TEF payments | - | - |
| Bradesco PJ INVESTMENTS | `001` | User does not have access to mutual funds / fixed income investments | Solicite ao usuário máster para ter acesso a esse serviço | Request master user to grant access |
| Bradesco PJ INVESTMENTS_TRANSACTIONS | `001` | User does not have access to investments transactions information | Solicite ao usuário máster para ter acesso a esse serviço | Request master user to grant access |
| Bradesco PJ INVESTMENTS_TRANSACTIONS | `001` | User doesn't have permissions to view fixed income / mutual funds txs | - | - |
| Bradesco PJ TRANSACTIONS | `001` | Transactions are not enabled for this account | Solicite ao usuário máster para ter acesso a esse serviço | Request master user to grant access |
| Caixa PJ TRANSACTIONS | `001` | Blocking situation to move your account | Situação impeditiva para movimentar sua conta. Procure sua agência para regularizar | Contact branch to regularize |
| XP INVESTMENTS | `001` | User does not have permissions to access Treasury assets | 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 | User must grant access to Treasury Direct |
| Sicoob PJ ACCOUNTS | `001` | User does not have permissions to get accounts | Usuário não tem permissão para executar a transação - Consultas - Saldo de conta corrente | Allow user access through Mobile App to account balance section |

> **Provider Messages**
>
> The `providerMessage` field contains the exact message from the Financial Institution in Portuguese, without any treatment. This way, the user can have a friendly and clear message of why this is happening. We don't provide a complete list of these messages since they are subject to changes by the FI.