Reporting Issues

Overview #

This guide explains how to understand issues that users may have and how to report them to Pluggy's support team.

When an item runs into an expected error, it will return in OUTDATED status, with ERROR as the execution status. Errors can occur after providing credentials, when the item starts connecting to the financial institution and begins providing responses/webhooks.

Unexpected Errors #

Unexpected errors are usually returned when the financial institution (FI) is unstable or when there is a case that was not mapped by Pluggy. If unexpected errors are consistent, you should report them to the team.

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

Connection Errors #

Connection errors occur after providing credentials, when the item starts connecting to the financial institution. These errors are typically related to:

Institution instability or downtime
Unmapped scenarios on Pluggy's side
Authentication changes at the institution

How to Report Issues #

When you are experiencing issues, the key is to provide enough context for the support team to investigate.

When using the widget, the user will end up on a screen with an unexpected error and an ErrorCode. If you are using Pluggy's Connect widget, this error will be shown in the widget. Report a screenshot of the widget to give the support team enough context.

Using the API Directly #

If you are creating your own UX, you will see the error in the HTTP POST /items response. Report the HTTP response to give the support team enough context.

Evidence: the itemId is mandatory

When using the widget, a screenshot of the error screen or the error code is enough.

It's strongly recommended for customers to track their users' attempts to connect, storing them as unsuccessful connections. You can capture the itemId through your Pluggy Connect widget implementation by catching the onError event, or through the item/error webhook event.

When connecting directly through the API, send the itemId exchanged in the API flow.

We can't analyze errors without an itemId, so it's mandatory that you capture and provide it.

Execution Report #

Further information about what has failed will be available in the Item executionReport field. If something goes fatally wrong with the connection, such as an unexpected error, and no data could be retrieved, the Item status will be OUTDATED and the related executionStatus will be ERROR.

The widget and HTTP response provide enough information for you to understand what is going wrong, and they give the support team the context needed to investigate the issue.

Errors When Providing Credentials (HTTP 400)#

Usually, this problem occurs when the user sends their credentials, but the creation of the Item is not successful. This means that the Item creation returns an HTTP 400 error for validations.

Usually, this means:

The credentials are not in the correct format.
There are missing credentials.
There is an active connection, or a duplicate connection was detected.

If you are using Pluggy's Connect widget, this error will be shown in the widget; if you are creating your own UX, you will see this error in the HTTP POST /items response. For more details on what errors are returned, you can check out the API reference.

Evidence

When you are having this type of issue, report a screenshot of the widget or the HTTP response to give the support team enough context. We expect that the widget and HTTP response provide enough information for you to understand what's going wrong.

Status Page #

Pluggy has a public status page where they post any incidents and outages so you can keep awareness of any existing issues. You can visit the status page at status.pluggy.ai.

You can also subscribe using the top button on the status page to get notified about incidents as soon as they happen. You can receive incident updates and maintenance status messages in Slack by subscribing.

For more information on subscribing to the status page, see Subscribe to our Status Page.