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:

FieldRequiredDescription
typeYesAn absolute URI that identifies the problem type. When dereferenced, it provides human-readable documentation for the problem type (for example, using HTML).
titleYesA short summary of the problem type. Written in English and readable for engineers.
statusYesThe HTTP status code generated by the origin server for this occurrence of the problem.
trace_idYesExtension. The TrueLayer trace identifier for the request
detailNoA human-readable explanation specific to this occurrence of the problem.
instanceNoAn 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 StatusDescriptionError CodeRetryHow to handle
200Success
400The supplied parameters are not valid.validation_errorYesThere's a problem with the request. Read the error message which explains what's wrong with the request specifically.
400The provider has been deprecated.deprecated_providerNoThe provider has been deprecated. It is no longer supported.
401The credentials or token are no longer validunauthorizedNoRefresh your access token. The access token may be invalid or expired. You can check for more details in the error description.
401The token is no longer validinvalid_tokenNoRefresh your access token. The access token may be invalid or expired. You can check for more details in the error description.
403Access to a specific resource has been denied.access_deniedNoAsk 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.
403The provided credentials encryption key is invalid.invalid_credentials_key
403SCA 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_exceededNoThe 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.
404The requested account cannot be found.account_not_foundNoCheck the accountId parameter used within your request. Confirm this matches an accountId returned from /accounts endpoint.
429Provider rate limit exceeded.provider_too_many_requestsYesInclude the X-PSU-IP header or retry later. Requests exceed the bank's rate limit.
429Maximum number of requests per user allowed by provider exceeded.provider_request_limit_exceededYesInclude 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).
500Internal server error.internal_server_errorYesRetry later.
501Feature not supported by the provider.endpoint_not_supportedNoCheck supported endpoints for each provider on our Supported Providers page on Console.
503The provider service is unavailable.provider_errorYesRetry later - the bank is currently undergoing maintenance.
503The connector service is currently overloaded.connector_overloadYesRetry later - TrueLayer is currently overloaded.
503The provider service is unavailable.temporarily_unavailableYesRetry later - the bank is experiencing unexpected downtime.
504The provider service timed out.provider_timeoutYesRetry later - the bank is experiencing issues.
504The connector service timed out.connector_timeoutYesRetry 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.

FieldTypeDescription
X-PSU-IPstringThe PSU's IP address to be passed on to the bank in order to avoid rate limiting.