Warnings & Status Codes

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). 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 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:

{
  "accounts": [...],
  "warnings": {
    "accounts": [
      {
        "code": "ACCT_002",
        "message": "Account c0a7d38c-d967-3b94-9d0b-c391068f4b20 is pending authorization"
      }
    ],
    "creditCards": [],
    "transactions": [],
    "loans": []
  }
}

{
  "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)

Credit Cards (CREDIT_CARDS)

Transactions (TRANSACTIONS)

Loans (LOANS)

Investments (INVESTMENTS)

Identity (IDENTITY)

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:

📘

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.