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 whenExtrato 365 dias
it'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 + 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. |
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 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. |
Updated about 2 months ago