Error Codes

Error body #

Every error, on every endpoint, has this shape:

Field	Meaning
`code`	The HTTP status, repeated. Always present.
`message`	A sentence for a person. Always present; not stable.
`codeDescription`	A stable identifier for the specific error, when the endpoint distinguishes several. Branch on this, not on `message`.
`data`	Extra detail for some errors — for instance, the Items that already exist when creating one would duplicate a connection.

Status codes #

Status	Meaning	Usually because
`400` Bad Request	The request is invalid.	A missing or malformed field (`INVALID_PARAMETERS`).
`401` Unauthorized	The credential is missing, wrong or expired.	An API Key past its 2 hours, or wrong `clientId`/`clientSecret` on `POST /auth` (`CLIENT_KEYS_UNAUTHORIZED`, `CLIENT_DISABLED`).
`403` Forbidden	The credential cannot reach this resource.	A Connect Token used outside its scope — see AuthenticationAPI.
`404` Not Found	No such resource.	An `id` that does not exist.
`405` Method Not Allowed	The endpoint does not support this verb.
`406` Not Acceptable	A format other than JSON was requested.
`409` Conflict	The request contradicts the current state of the resource.	A conflict updating an Item — see `PATCH /items/{id}`API.
`429` Too Many Requests	A rate limit was exceeded.	See Rate LimitsAPI for the limits and the `Retry-After` header.
`500` Internal Server Error	Something failed on our side.	Retry later.
`503` Service Unavailable	Temporarily offline for maintenance.	Retry later.

Each endpoint's page in this reference lists the statuses it returns and, where the API distinguishes them, the codeDescription values.

Invalid parameters #

`codeDescription`	Status	Message	What to do
`INVALID_PARAMETERS`	`400`	Names the parameter and the problem — for instance `accountId must be a UUID` or `property pageSize should not exist`.	A path, query or body parameter is missing, malformed, or not accepted by the endpoint. Fix the parameter named in the message; retrying the same request returns the same error.

Creating and updating an Item #

These come back from POST /itemsAPI and PATCH /items/{id}API. Where the text below shows a :placeholder, the real message carries the value — a frequency, a wait, a parameter name.

`codeDescription`	Status	Message	What to do
`PARAMETERS_NOT_PROVIDED`	`400`	parameters were not provided	Send the connection's credentials to sync the item.
`ITEM_ALREADY_UPDATING`	`400`	An update is already in progress, wait until the last execution ends	This item is syncing. Wait for the execution to finish — success or error — before triggering another.
`ITEM_IS_ALREADY_UPDATING`	`400`	There is an active item for the set of credentials that hasn't finished executing	The same set of credentials is syncing on another item. Wait for it, so two sessions are not opened with the institution at once.
`CLIENT_IS_UPDATING_BEFORE_ALLOWED_FREQUENCY`	`409`	Client updates on this item are allowed at most every :minUpdateFrequencyAllowedInHours hours. Last update was at :lastUpdatedAt	Wait until the minimum frequency has passed since the last update. The limit is per team and adjustable — ask support if your use case needs a shorter one.
`LAST_EXECUTION_HAD_LOGIN_ERROR`	`400`	Last execution had a login error, you must update the parameters	The last sync failed to log in. Send new credentials before updating again.
`TOO_MANY_CONSECUTIVE_LOGIN_FAILURES`	`400`	must wait at least :readableBackoffTime after :maxConsecutiveFailedLoginAttempts consecutive login errors, last attempt was at :lastExecutionEndedAt (can retry after: :canRetryAfterDate)	A cooldown after repeated login errors, so the user's account is not locked by the institution. Retry after the time in the message.
`TOO_MANY_CONSECUTIVE_ERRORS`	`400`	There has been more than 5 failing syncronizations, please contact support	The connection failed too many times in a row. Report it to support with the `itemId`.
`ITEM_IN_ERROR_COOLDOWN`	`409`	This set of credentials recently failed to connect and is in a cooldown period, please try again later	These credentials failed recently and are in a cooldown. Retry after it passes.
`CONNECTOR_OFFLINE`	`409`	this connector is offline in this moment	The connector is not accepting executions right now. Try again later — see status.pluggy.ai.
`CONNECTOR_REQUIRED_PARAMETER_VALIDATION_ERROR`	`400`	The parameter :parameter is required to be renewed for item update.	The connector now requires that parameter again. Send it to update the connection.
`ITEM_ORIGINAL_CONNECTED_WITH_DIFFERENT_ACCOUNT`	`409`	Item was originally connected with a different account, please use the original account	The credentials now point at a different account than the one the item was created with. Use the original account, or create a new item.
`ITEM_CREATION_LIMIT_EXCEEDED`	`409`	Client exceeded item creation limit (:itemsLimit items) for the current subscription level.	You reached the item limit of your subscription. Delete unused items or contact support.
`CLIENT_HAS_ITEM_UPDATES_DISABLED`	`409`	Client has item updates disabled	Updates were disabled for the team. Contact support.
`CREATE_ITEMS_API_FREE_DISABLED`	`400`	Free subscription can only create items through our Connect Widget	On the free subscription, items are created through the Connect Widget.
`SANDBOX_CLIENT_ITEM_UPDATE_NOT_ALLOWED`	`400`	Current client subscription level can only update Sandbox (Pluggy Bank) items	Your subscription level only allows updating Sandbox (Pluggy Bank) items.
`TRIAL_CLIENT_ITEM_CREATE_NOT_ALLOWED`	`400`	Trial clients can only create Sandbox (Pluggy Bank) items	During the trial, items can only be created on Sandbox (Pluggy Bank) connectors and on the MeuPluggy connector. Use those while on trial, or upgrade your subscription to connect other institutions.
`MEU_PLUGGY_ITEM_UPDATE_NOT_ALLOWED`	`400`	MeuPluggy item cant be updated	MeuPluggy items are kept up to date by MeuPluggy itself and cannot be updated with `PATCH /items/{id}`. Read the data with the item's endpoints; there is nothing to trigger.

Most of these share status 400, so branch on codeDescription, not on the status. Only some of them need the end user, and only the "wait and retry" ones go away by retrying: the rest need a change in your request, your subscription or a support ticket. In every case, keep showing the data you already have.

This table covers every code above and every MFA error below.

`codeDescription`	Requires the user	Who acts
`PARAMETERS_NOT_PROVIDED`	Yes	The user — enters the connection's credentials.
`LAST_EXECUTION_HAD_LOGIN_ERROR`	Yes	The user — enters new credentials.
`CONNECTOR_REQUIRED_PARAMETER_VALIDATION_ERROR`	Yes	The user — provides the parameter named in the message again.
`ITEM_ORIGINAL_CONNECTED_WITH_DIFFERENT_ACCOUNT`	Yes	The user — reconnects with the original account, or creates a new item.
`ITEM_MFA_EXPIRED`	Yes	The user — starts a new update and enters a new MFA value.
`MFA_PARAMERTER_WAS_ALREADY_USED_ERROR`	Yes	The user — enters a new MFA value.
`ITEM_ALREADY_UPDATING`	No	Nobody — wait for the running execution and retry.
`ITEM_IS_ALREADY_UPDATING`	No	Nobody — wait for the other item's execution and retry.
`CLIENT_IS_UPDATING_BEFORE_ALLOWED_FREQUENCY`	No	Nobody — wait for the minimum frequency and retry.
`TOO_MANY_CONSECUTIVE_LOGIN_FAILURES`	No	Nobody — wait for the cooldown in the message and retry.
`ITEM_IN_ERROR_COOLDOWN`	No	Nobody — wait for the cooldown and retry.
`CONNECTOR_OFFLINE`	No	Nobody — retry when the connector is back online.
`ITEM_MFA_PARAMETER_EXPECTED_MISMATCH`	No	Your integration — send the value under the parameter name in the message.
`ITEM_MFA_NOT_FOUND`	No	Your integration — only send MFA while the item is waiting for it.
`ITEM_MFA_ALREADY_PROVIDED`	No	Your integration — nothing to send; the MFA was already received.
`MISSING_MFA_PARAMETER_DATA`	No	Your integration — the request had no MFA parameters; send them.
`MISSING_MFA_PARAMETER_VALUE`	No	Your integration — a parameter was sent empty; send the value (if the user left the field blank, ask them for it before sending).
`TOO_MANY_CONSECUTIVE_ERRORS`	No	Pluggy support — report it with the `itemId`.
`ITEM_CREATION_LIMIT_EXCEEDED`	No	Your subscription — delete unused items or contact support.
`CLIENT_HAS_ITEM_UPDATES_DISABLED`	No	Pluggy support.
`CREATE_ITEMS_API_FREE_DISABLED`	No	Your subscription — create items through the Connect Widget, or upgrade.
`SANDBOX_CLIENT_ITEM_UPDATE_NOT_ALLOWED`	No	Your subscription.
`TRIAL_CLIENT_ITEM_CREATE_NOT_ALLOWED`	No	Your subscription — use Sandbox connectors during the trial, or upgrade.
`MEU_PLUGGY_ITEM_UPDATE_NOT_ALLOWED`	No	Your integration — don't send updates for MeuPluggy items.

Open Finance updates do not need the user

For an Open Finance item, an update with PATCH /items/{id}API never needs the user: it reads the data under the consent the user already gave. The exception is an item that already requires the user's action before the update, which you can see on the item itself:

status is WAITING_USER_ACTION (the user still has to authorise at the institution), or executionStatus is USER_AUTHORIZATION_PENDING;
executionStatus is USER_AUTHORIZATION_REVOKED (the user revoked the consent at the institution), USER_AUTHORIZATION_EXPIRED (the consent expired) or USER_AUTHORIZATION_NOT_GRANTED (the consent was never authorised);
consentExpiresAt is in the past: the next update ends in USER_AUTHORIZATION_EXPIRED.

In those cases the user has to go through the institution's authorisation again — see Consents.

MFA errors #

Returned when sending a multi-factor parameter to an Item — see Updating an Item.

`codeDescription`	Status	Message	What to do
`ITEM_MFA_NOT_FOUND`	`404`	item has no mfa input request	The item is not waiting for an MFA input, so none can be submitted.
`ITEM_MFA_ALREADY_PROVIDED`	`400`	item has no mfa input request, it was already provided	Nothing to do — the MFA was already submitted.
`ITEM_MFA_EXPIRED`	`400`	Item's MFA parameter expired, please start a new update	The MFA window closed. Start a new update to sync the connection.
`ITEM_MFA_PARAMETER_EXPECTED_MISMATCH`	`400`	Item is expecting ':parameter' MFA param name	The item is waiting for a different parameter. Use the name in the message.
`MFA_PARAMERTER_WAS_ALREADY_USED_ERROR`	`400`	MFA parameter has to be updated from last execution	The value sent is the one already used in the last execution. Ask the user for a new one.
`MISSING_MFA_PARAMETER_DATA`	`400`	Missing MFA parameter data	The request had no MFA parameters. Send the parameter the item is waiting for.
`MISSING_MFA_PARAMETER_VALUE`	`400`	Missing ':parameter' MFA parameter value	The parameter named in the message was sent empty. Send its value.

MFA_PARAMERTER_WAS_ALREADY_USED_ERROR

That spelling is not a typo in this page: the API returns PARAMERTER. Match it exactly if you branch on it.

Transactions #

`codeDescription`	Status	Message	What to do
`ENDPOINT_DEPRECATED`	`410`	This endpoint is deprecated. Use GET /v2/transactions with cursor pagination instead.	`GET /transactions` is closed for applications created on or after 2026-06-02 00:00 Brasília time (03:00 UTC), and available to everyone else only until 2026-12-31. Use `GET /v2/transactions`API — see the migration tableAPI.

Read the guide: Errors Codes.

Error body#

Status codes#

Invalid parameters#

Creating and updating an Item#

Who has to act#

MFA errors#

Transactions#