When connecting an Item, if everything went well, the GET /items/:id endpoint 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": "USER_AUTHORIZATION_NOT_GRANTED",
  "error": {
    "code": "USER_AUTHORIZATION_NOT_GRANTED",
    "message": "The user did not grant necessary permissions for their account."
  },
  "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

After a successful login, there can be 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), the item will have status OUTDATED:

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

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": {
    "code": "UNEXPECTED_ERROR",
    "message": "Unexpected error."
  },
  "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
  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"
  }
}

 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, however, there is only a subset of possible 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:

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