Errors & Validations

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: