Verification API errors

Our endpoint returns a Problem JSON on client usage errors (4xx status codes) as well as server side processing errors (5xx status codes).

RFC 7807 defines a Problem JSON object using the media type application/problem+json. It provides extensible human and machine-readable failure information beyond the HTTP response status code. The information includes details such as the kind of failure (type / title) and its cause and location (instance / detail). The following table describes the fields we return:

Field	Required	Description
`type`	Yes	An absolute URI that identifies the problem type. When dereferenced, it provides human-readable documentation for the problem type (for example, using HTML).
`title`	Yes	A short summary of the problem type. Written in English and readable for engineers.
`status`	Yes	The HTTP status code generated by the origin server for this occurrence of the problem.
`trace_id`	Yes	Extension. The TrueLayer trace identifier for the request
`detail`	No	A human-readable explanation specific to this occurrence of the problem.
`instance`	No	An absolute URI that identifies the specific occurrence of the problem.

Verification API Error Codes

The following error codes can be returned with the associated HTTP status.

HTTP Status	Description	Error Code	Retry	How to handle
`200`	Success
`400`	The supplied parameters are not valid.	`validation_error`	Yes	There's a problem with the request. Read the error message which explains what's wrong with the request specifically.
`400`	The provider has been deprecated.	`deprecated_provider`	No	The provider has been deprecated. It is no longer supported.
`401`	The credentials or token are no longer valid	`unauthorized`	No	Refresh your access token. The access token may be invalid or expired. You can check for more details in the error description.
`401`	The token is no longer valid	`invalid_token`	No	Refresh your access token. The access token may be invalid or expired. You can check for more details in the error description.
`403`	Access to a specific resource has been denied.	`access_denied`	No	Ask the user to reconnect their account. This error is returned when the access to their account is no longer valid, either because it expired or because the user revoked it themselves.
`403`	The provided credentials encryption key is invalid.	`invalid_credentials_key`
`403`	SCA exemption has expired. This resource is protected and should be accessed shortly after PSU Authentication. In order to access this resource, please have the PSU re-authenticate.	`sca_exceeded`	No	The access to that specific endpoint has expired. For example, for some European banks you may only access the /info endpoint, or transanctions older than 90 days, during the 5 minutes after the user first grants access. Access to other data (balances, recent transactions) should still be working.
`404`	The requested account cannot be found.	`account_not_found`	No	Check the accountId parameter used within your request. Confirm this matches an accountId returned from /accounts endpoint.
`429`	Provider rate limit exceeded.	`provider_too_many_requests`	Yes	Include the X-PSU-IP header or retry later. Requests exceed the bank's rate limit.
`429`	Maximum number of requests per user allowed by provider exceeded.	`provider_request_limit_exceeded`	Yes	Include the X-PSU-IP header or retry later. The bank has a regulatory limit on how often the account can be accessed (for example, many European banks have a limit of 4 requests for a given user per endpoint per day, unless the user has initiated the request).
`500`	Internal server error.	`internal_server_error`	Yes	Retry later.
`501`	Feature not supported by the provider.	`endpoint_not_supported`	No	Check supported endpoints for each provider on our Supported Providers page on Console.
`503`	The provider service is unavailable.	`provider_error`	Yes	Retry later - the bank is currently undergoing maintenance.
`503`	The connector service is currently overloaded.	`connector_overload`	Yes	Retry later - TrueLayer is currently overloaded.
`503`	The provider service is unavailable.	`temporarily_unavailable`	Yes	Retry later - the bank is experiencing unexpected downtime.
`504`	The provider service timed out.	`provider_timeout`	Yes	Retry later - the bank is experiencing issues.
`504`	The connector service timed out.	`connector_timeout`	Yes	Retry later - TrueLayer is experiencing a transient issue.

End-user IP Address

EU banks limit the number of requests that can be made to their API if the request is not initiated by the end-user. These are documented as 429 errors in the table earlier on this page. In order to avoid this rate limit, you can include the end-user's IP address in your requests to the Data API as follows.

Field	Type	Description
`X-PSU-IP`	string	The PSU's IP address to be passed on to the bank in order to avoid rate limiting.