Errors & Validations

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

Partial Products Errors

Sometimes we fail to recover a specific product while creating a connection with the institution, due to a problem with the connection or instability on the provider. In this scenario, the Item will land on a PARTIAL_SUCCESS executionStatus, and the attribute statusDetail will provide more information on the product collection.

{
    "accounts": {
      "isUpdated": true,
      "lastUpdatedAt": "2022-03-08T22:43:04.796Z",
      "warnings": []
    },
    "identity": {
      "isUpdated": false,
      "lastUpdatedAt": null,
      "warnings": []
    },
    "creditCards": {
      "isUpdated": true,
      "lastUpdatedAt": "2022-03-08T22:43:04.796Z",
      "warnings": []
    },
    "investments": {
      "isUpdated": true,
      "lastUpdatedAt": "2022-03-08T22:43:04.796Z",
      "warnings": []
    },
    "transactions": {
      "isUpdated": true,
      "lastUpdatedAt": "2022-03-08T22:43:04.796Z",
      "warnings": []
    },
    "paymentData": null
}

There are different scenarios that a product shows:

Product updated

When the product is updated, the lastUpdatedAt date will be updated with the synchronization timestamp, as well as the isUpdated flag will be updated to easily compare/filter updated products.

{
  "isUpdated": true,
  "lastUpdatedAt": "2022-03-08T22:43:04.796Z"
}

Product was not updated

There was an issue when collecting the product, in this case the isUpdated will reflect this situation and the lastUpdatedAt date will showcase when it was the last synchronization. If the product was never collected it will return null.

{
  "isUpdated": false,
  "lastUpdatedAt": null
}
{
  "isUpdated": false,
  "lastUpdatedAt": "2022-03-08T22:43:04.796Z"
}

Product was not requested

For products that were not requested to Pluggy API, we won't return any details about it.

{
  "paymentData": null
}

Product warnings

There are cases where a Product can not be recovered and an error does not cause it, it's an expected behavior of the Financial Institution. For example, when the user connecting lacks permission to view a specific product in the institution.

In these cases, the resulting item status is SUCCESS, and we include the statusDetail field with each product's warnings. Pluggy does not modify the providerMessage, it is extracted directly from the institution if it's provided.

The code and the message fields are generated by Pluggy for developers to easily integrate and will be consistently in English across all connectors.

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

Codes

  • 001: Lack of permissions to access particular products.
  • 002: The user has limited permission, so the data can be recovered with limitations (ie. Instead of 12 months, can recover 3 months).
  • 003: The connection hit a limit by the FI that can't be overcome. As an example, Santander PJ only returns 400 transactions per day when Extrato 365 diasit's not enabled.

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"
    }
  ]
}

The Error object

Following type represents the complete error structure. In next examples we explain the use of each field of this object.

type ExecutionErrorResult = {
  code: ExecutionErrorCodes // https://docs.pluggy.ai/docs/item-lifecycle#error-state 
  message: string
  providerMessage?: string
  attributes?: Record<string, string>
}

When there was an error with the whole item execution (for example, due invalid credentials), the item is returned with an error object with more useful information, like code and message:

{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid credentials."
  }
}

Also, with certain errors, the error object is returned with an attributes key with additional information necessary for future executions. This is an example of a USER_AUTHORIZATION_PENDING error, deviceNickname will be used in the next execution:

{
  "error": {
    "code": "USER_AUTHORIZATION_PENDING",
    "message": "The user needs to grant necessary permissions for their account.",
    "attributes": {
      "deviceNickname": "123456789"
    }
  }
}

In other cases, when error code is ACCOUNT_NEED_ACTIONS, when it's possible, we use a field calls providerMessage in which we add relevant information returned by the institution related to the action needed:

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

For example it's used when a user is asked to change account password or complete account data needed.

Conflicts trying to update an item

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

  • Item is already updating.
  • Client update on the item is not allowed because item was updated before the client minimum frequency.

In both cases API users are going to receive a 409 status and the specific message explain why they can't update the item.

Troubleshooting warnings

Here is a list of known warnings for Direct Connectors:

Connector + ProductmessageproviderMessageAction item
Itaú PF
INVESTMENTS_TRANSACTIONS
User needs to verify cadastroUser needs to access the corretora webpage and verify their registration
Itaú PF
INVESTMENTS_TRANSACTIONS
Treasury market is closed at this timeUser 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 assetsA 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.
Orama
INVESTMENTS
Could not retrieve Tesouro Directo rates
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 informationSolicite ao usuário máster para ter acesso a esse serviço.
Bradesco PJ
CREDIT_CARDS
User does not have access to credit card informationSolicite 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 informationSolicite ao usuário máster para ter acesso a esse serviço.
Bradesco PJ
INVESTMENTS_TRANSACTIONS
User does not have access to investments transactions informationSolicite 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 accountSolicite 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 dataConsulte seu gerente ou Central de Atendimento para liberar permissões
Itaú PJ
PAYMENT_DATA
Client does not have permissions to see PIX payment dataCliente não tem permissão para acesso a PIXGrant user access to this section.
Itaú PJ
INVESTMENTS
001 - User doesn't have permissions to view investmentsGrant 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 AccountsAllow operator to access the accounts section.
Santander PJ
CREDIT_CARDS
001 - User doesn't have permissions, cannot recover credit cardsAllow 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 assetsA 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 accountsUsuário não tem permissão para executar a transação - Consultas - Saldo de conta correnteAllow user to access through Mobile App to the "Saldo de conta corrente" section.