Data API V3 errors
Error responses (status codes
4xx+5xx) from our Data API v3 conform to the Problem Details standard in the IETF specification.
Below is a table with all Data API v3 errors. The type and title fields identify the error, and the detail field explains exactly what went wrong.
| Code | Type | What to do if you see this error |
|---|---|---|
| 401 | Unauthenticated | Get a new access token. The token is missing, malformed, or expired. |
| 400 | Invalid Parameters | Check the errors field included in the response for the request body field, query parameter, or header name that was invalid. The errors will also include at least one description of the error for each invalid field. |
| 403 | Forbidden | Check that your token has the data scope. If the user revoked access, or the Strong Customer Authentication window has expired, ask the user to reconnect their account. |
| 400 | Invalid State | The data connection is no longer authorized, so no data can be retrieved through it. Ask the user to reconnect their account. |
| 404 | Not Found | Check the Connection-Id header and the identifiers in your request path. |
| 429 | Rate Limit Exceeded | Include the Tl-User-IP header, or try again later. |
| 502 | Feature Not Supported | Don't retry. The provider doesn't support this endpoint or feature. |
| 502 | Provider Error | Try again, or wait for the provider to be available again and retry. |
| 500 | Unknown Error | Try again, or contact Support if the problem continues. |
Include thetrace_idwhen contacting TrueLayer SupportIf you experience an error when integrating our Data API, you will receive a
trace_idin the response. Store this.If you need to contact Support, include the
trace_idto help us identify your request.
Unauthenticated
The token provided is missing, malformed, or expired.
{
"type": "<https://docs.truelayer.com/docs/data-v3-errors#unauthenticated>",
"title": "Unauthenticated",
"status": 401,
"trace_id": "96ce50247f87f540bb2d86771b3728b8",
"detail": "A valid Bearer token must be provided in the Authorization header."
}Forbidden
The token or connection doesn’t have the permission to perform the request. This occurs if the token doesn’t have the required scope(s).
{
"type": "<https://docs.truelayer.com/docs/data-v3-errors#forbidden>",
"title": "Forbidden",
"status": 403,
"trace_id": "96ce50247f87f540bb2d86771b3728b8",
"detail": "The token used for Authorization is not authorized to perform the request."
}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.
{
"type": "<https://docs.truelayer.com/docs/data-v3-errors#forbidden>",
"title": "Forbidden",
"status": 403,
"trace_id": "96ce50247f87f540bb2d86771b3728b8",
"detail": "The Strong Customer Authentication consent has expired. This resource is accessible shortly after Payment Service User authentication, re-authenticate to continue"
}Invalid Parameters
One or more request body fields, query parameters, or headers were invalid.
{
"type": "<https://docs.truelayer.com/docs/data-v3-errors#invalid-parameters>",
"title": "Invalid Parameters",
"status": 400,
"trace_id": "96ce50247f87f540bb2d86771b3728b8",
"detail": "The request was invalid.",
"errors": {
"Connection-Id": [
"Must be a valid GUID."
]
}
}Invalid State
The requested operation is not valid, given the current state of the resource. This can occur if, for example, the data connection isn’t in an authorized state.
{
"type": "<https://docs.truelayer.com/docs/data-v3-errors#invalid-state>",
"title": "Invalid State",
"status": 400,
"trace_id": "96ce50247f87f540bb2d86771b3728b8",
"detail": "The data connection is not in an authorized state."
}Not Found
The requested resource cannot be found. This can occur if an incorrect resource identifier is used in the request path or header.
{
"type": "<https://docs.truelayer.com/docs/data-v3-errors#not-found>",
"title": "Not Found",
"status": 404,
"trace_id": "96ce50247f87f540bb2d86771b3728b8",
"detail": "The account was not found."
}Rate Limit Exceeded
Too many requests have been made to TrueLayer, or to the provider.
Providers limit how often an account can be accessed when the request isn't initiated by the end user. Many European banks allow only 4 requests per user, per endpoint, per day. Include the end user's IP address in the Tl-User-IP header to avoid this limit, or retry later.
{
"type": "<https://docs.truelayer.com/docs/data-v3-errors#rate-limit-exceeded>",
"title": "Rate Limit Exceeded",
"status": 429,
"trace_id": "96ce50247f87f540bb2d86771b3728b8",
"detail": "The provider has rate limited this request. Retry later."
}Feature Not Supported
The provider doesn't support this endpoint or feature.
{
"type": "<https://docs.truelayer.com/docs/data-v3-errors#feature-not-supported>",
"title": "Feature Not Supported",
"status": 502,
"trace_id": "96ce50247f87f540bb2d86771b3728b8",
"detail": "This feature is not supported by the provider."
}Provider Error
The provider is temporarily unavailable or returned an error.
{
"type": "<https://docs.truelayer.com/docs/data-v3-errors#provider-error>",
"title": "Provider Error",
"status": 502,
"trace_id": "96ce50247f87f540bb2d86771b3728b8",
"detail": "The provider is currently unavailable. Retry later."
}Unknown Error
An unexpected error has occurred.
{
"type": "<https://docs.truelayer.com/docs/data-v3-errors#unknown-error>",
"title": "Unknown Error",
"status": 500,
"trace_id": "96ce50247f87f540bb2d86771b3728b8",
"detail": "An unexpected error occurred. Retry later."
}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 above. 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 |
|---|---|---|
Tl-User-IP | string | The PSU’s IP address to be passed on to the bank in order to avoid rate limiting. |
Updated about 5 hours ago