Errors & Validations

Learn about the different statuses and errors you could face using Pluggy's API.

When connecting an Item, if connection was successful and all products were retrieved correctly, GET /items/:id will return something like this:

{
  "id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
  "status": "UPDATED", // Products were retrieved
  "executionStatus": "SUCCESS", // ALL products were updated
  "lastUpdatedAt": "2024-09-27T14:51:46.216Z",
  "error": null,
  "statusDetail": null
  ...
}

If the execution status is SUCCESS, it means every product (accounts, transactions, etc) was retrieved correctly from the institution, and is ready to be retrieved.

Item failed to log in

When creating or updating an item, we could fail to log in, which returns a status LOGIN_ERROR:

{
  "id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
  "status": "LOGIN_ERROR", // Could not log in
  "executionStatus": "INVALID_CREDENTIALS",
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid credentials."
  },
  "statusDetail": null,
  ...
}

Here, no product was retrieved, and we cannot retry the connection: we require the user to update their credentials.

 Item failed to begin retrieving products

There are situations where we are unable to retrieve any products (for example, the institution is down, the institution tells us there is another active session and kicks us out, etc), but it is not necessarily a problem with the login. In these cases the item will have status OUTDATED:

{
  "id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
  "status": "OUTDATED", // Could not update any products
  "executionStatus": "CONNECTION_ERROR",
  "error": {
    "code": "CONNECTION_ERROR",
    "message": "Connectivity error, please try again."
  },
  "statusDetail": null,
  ...
}

When the institution is having an instability the executionStatus will be SITE_NOT_AVAILABLE, however, when it's an unexpected error on our side, the executionStatus will be ERROR or CONNECTION_ERROR.

You can try to update the item again to see if the issue persists (for example, the bank could be unstable in the morning, but recover later during the day).

If you have auto-sync, OUTDATED items are retried automatically up to 5 times, with 1 hour between each attempt. If it fails 5 times, it is dropped from auto-sync.

 Item failed to retrieve a specific product

Sometimes we access the institution correctly, but a certain product cannot be retrieved. This will yield a status of UPDATED with an execution status of PARTIAL_SUCCESS. The field statusDetail will have information about which products failed.

{
  "id": "1b0f3cd5-c902-4836-b68b-04cbd847f99a",
  "status": "UPDATED", // Products were retrieved
  "executionStatus": "PARTIAL_SUCCESS", // Some products failed
  "error": null,
  "statusDetail": {
    "accounts": { // Was retrieved correctly
      "warnings": [],
      "isUpdated": true,
      "lastUpdatedAt": "2024-01-23T22:39:55.622Z"
    },
    "transactions": {
      "warnings": [],
      "isUpdated": false, // Failed
      "lastUpdatedAt": "2024-01-21T22:39:55.622Z" // Last successful update of the product
    },
    "creditCards": null, // Product not part of item
  },
  ...
}

You can also retry these cases to see if the issue persists. Auto-sync does not retry PARTIAL_SUCCESS.

 The Error object

The following type represents the complete error structure:

type ExecutionErrorResult = {
  code: ExecutionErrorCodes // https://docs.pluggy.ai/docs/item-lifecycle#error-state 
  message: string
  providerMessage?: string // Value provided by the FI that gives more information/context
  attributes?: Record<string, string>
}

With certain errors, the error object is returned with an attributes key with additional information necessary for future executions:

{
  "error": {
    "code": "USER_AUTHORIZATION_PENDING",
    "message": "The user needs to grant necessary permissions for their account.",
    "attributes": {
      "deviceNickname": "123456789" // We must tell the user this is the device name
                                    // to authorize in their bank website
    }
  }
}

When the error code is ACCOUNT_NEEDS_ACTION, we use a field called providerMessage in portuguese, with any relevant alert message from the institution:

{
  "error": {
    "code": "ACCOUNT_NEEDS_ACTION",
    "message": "Account needs a manual user action.",
    "providerMessage": "Your password should be changed"
  }
}

The providerMessage field is the exact message returned by the Financial Institution when running into an error, without any treatment. This way, the user can have a friendly and clear message of why this is happening.
We don't provide a list of these messages since they are subject to changes by the FI.


 Warnings

Warnings are useful information about product retrieval, and are included in the statusDetailon 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.

Warnings include a providerMessage in portuguese, that you could show to your end user to instruct them on what to do. Example:

{ 
  "statusDetail": {
    "investments": {
      "isUpdated": true,
      "lastUpdatedAt": "2022-03-08T22:43:04.796Z",
      "warnings": [
        {
          "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."
        }
      ]
    },
    ...
  }
  ...
}

Handling errors

Error handling logic, in general, can look something like this:

  • If executionStatus is SUCCESS
    • Fetch all products (transactions, accounts, etc)
    • Check the warnings (if any) to see information about how data could be improved.
  • If executionStatus is PARTIAL_SUCCESS
    • Fetch all isUpdated: true products
    • Raise an internal alert if it's a critical product (e.g. TRANSACTIONS) or add a user alert.
    • Check the warnings (if any) to see information about why the product failed.
  • If status is LOGIN_ERROR (Open Finance doesn't require handling this case):
    • Don't fetch any products
    • Prompt the user to input their credentials again
  • If status is OUTDATED:
    • Don't fetch any products
    • Raise an internal alert or add a user alert

For direct connectors, all error cases are described here.

Open Finance error cases

For Open Finance, there is only a subset of possible error cases, as follows, divided by status and executionStatus:

  • LOGIN_ERROR:
    • INVALID_CREDENTIALS: the CPF/CNPJ is invalid
    • USER_AUTHORIZATION_NOT_GRANTED: the user rejected the consent while in the authorization flow
    • USER_AUTHORIZATION_REVOKED: the user revoked the consent from their bank
  • OUTDATED:
    • USER_INPUT_TIMEOUT: the user never finished the authorization flow
    • SITE_NOT_AVAILABLE: the institution is currently unstable
    • ERROR/CONNECTION_ERROR: an unexpected error occurred while accessing the institution
  • UPDATED:
    • PARTIAL_SUCCESS: failed to retrieve a product, most likely because the monthly rate limit has been reached, or because the institution has a temporary instability on that product.

Troubleshooting warnings

Here is a list of known warnings for Direct Connectors:

Connector + Product

message

providerMessage

Action item

Itaú PF INVESTMENTS_TRANSACTIONS

User needs to verify cadastro

User needs to access the corretora webpage and verify their registration

Itaú PF
INVESTMENTS_TRANSACTIONS

Treasury market is closed at this time

User must retry at business hours.

Bradesco PF
Login

O usuário deve acessar a conta manualmente para resolver o captcha.

Clear
INVESTMENTS

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 seu assessor.

Contact broker to setup the account.

Banco do Brasil PJ
ACCOUNTS

User does not have permissions to access this account

Banco do Brasil PJ
CREDIT_CARDS

User does not have permissions to access credit card's transactions

Banco do Brasil PJ
INVESTMENTS

User without permissions to get mutual funds / fixed incomes

Banco do Brasil PJ
INVESTMENTS

Hour not allowed to get fixed incomes

Bradesco PJ
ACCOUNTS

User does not have access to accounts information

Solicite ao usuário máster para ter acesso a esse serviço.

Bradesco PJ
CREDIT_CARDS

User does not have access to credit card information

Solicite ao usuário máster para ter acesso a esse serviço

Bradesco PJ
PAYMENT_DATA

User doesn't have permissions to obtain TED / PIX / TEF payments

Bradesco PJ
INVESTMENTS

User does not have access to mutual funds / fixed income investments information

Solicite ao usuário máster para ter acesso a esse serviço.

Bradesco PJ
INVESTMENTS_TRANSACTIONS

User does not have access to investments transactions information

Solicite ao usuário máster para ter acesso a esse serviço.

Bradesco PJ
INVESTMENTS_TRANSACTIONS

User doesn't have permissions to view fixed income / mutual funds transactions

Bradesco PJ
TRANSACTIONS

Transactions are not enabled for this account

Solicite ao usuário máster para ter acceso a esse serviço.

Caixa PJ
TRANSACTIONS

Situação impeditiva para movimentar sua conta. Procure sua agência para regularizar.

Itaú PJ
CREDIT_CARDS

User dont have access to credit cards resumes

Itaú PJ
PAYMENT_DATA

User doesn't have permission to obtain received PIX QR code payment data

Consulte seu gerente ou Central de Atendimento para liberar permissões

Itaú PJ
PAYMENT_DATA

Client does not have permissions to see PIX payment data

Cliente não tem permissão para acesso a PIX

Grant user access to this section.

Itaú PJ
INVESTMENTS

  • *001** - User doesn't have permissions to view investments

Grant user access to this section.

Santander PJ
ACCOUNTS

  • *002** - User doesn't have access to 'Extrato 365 dias', we got information from 'Saldo e Extrato'.

N/A

Santander PJ
ACCOUNTS

  • *001** - Operator doesn't have access to Accounts

Allow operator to access the accounts section.

Santander PJ
CREDIT_CARDS

  • *001** - User doesn't have permissions, cannot recover credit cards

Allow operator to access the credit cards section.

Santander PJ
TRANSACTIONS

  • *003** - User doesn't have access to 'Extrato 365 dias' or it's offline, we got information from 'Saldo e Extrato'. Information here is limited to 90 days and 400 txs.

Since this section offers a limited data retrieval, allowing access to Extrato 365 would solve the days / data limitation.

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 seu assessor.

User must grant access to this product to be recovered.

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 to access through Mobile App to the "Saldo de conta corrente" section.

Item Creation Validations

Validations in Pluggy API are very important. They are used to avoid executing connectors with invalid parameters and to create item connections that won't be synced due to invalid credentials or parameters. When creating or updating an item, validations will be executed for that item based on the connector's credentials.

This is an example of a validation response when creating an item:

{  
  "message": "Connector parameters do not match validation rules",  
  "errors": [  
    {  
      "code": "002",  
      "message": "user parameter length must be at least 6.",  
      "parameter": "user"  
    },  
    {  
      "code": "002",  
      "message": "password parameter length must be at least 6.",  
      "parameter": "password"  
    }  
  ]  
}

Update rejection errors

There are some cases in which an item could not be updated due to the state of the item:

Status

Code

Code

Description

Action Item

409

ITEM_IS_ALREADY_UPDATING

The item is already updating

Wait for the item to finish the existing sync.

409

ITEM_CREATION_LIMIT_EXCEEDED

Can't update on the item is not allowed because the item was updated before the client's minimum frequency

Wait until the contracted delay has happened.

409

CLIENT_HAS_ITEM_UPDATES_DISABLED

The client can't trigger manual updates since it was disabled by Pluggy

Contact the support team to understand why the client was disabled for updates.

400

ITEM_ORIGINAL_CONNECTED_WITH_DIFFERENT_ACCOUNT

Item was originally connected with a different account, please use the original account

The user initially connected with a different company/account, they cant change the connection configuration.