Payments API errors

📘
Error responses (status codes 4xx + 5xx) from our Payments API v3 conform to the Problem Details standard in the IETF specification.

Below is a table with all Payments v3 errors. Find more information about exactly what went wrong in error responses.

Code	Type	What to do if you see this error
401	Unauthenticated	Check the authorisation requirements of the endpoint, and send an appropriate token and signature (if applicable) in the headers.
403	Forbidden	If you're using an `access_token` from our authentication endpoint, check if the token has scopes that the endpoint requires. If you're using a `resource_token`, check if you're trying to access a resource other than the one the token was issued for.
400	Invalid Parameters	Check the `errors` field included in the response for the JSON path of the request body fields or the header names that were invalid. The errors will also include at least one description of the error for each invalid field.
400	Invalid State	Check if the next requested action is valid. For example, if you've tried to submit the provider selection, but the next authorised action is redirection.
404	Not Found	Check your payment ID value in the request path.
409	Concurrency Conflict	This resource is already being used in another request. Try again later.
409	Idempotency-Key Concurrency Conflict	Check if there's another request using the same Idempotency-Key header value currently in progress.
422	Idempotency-Key Reuse	Use a unique Idempotency-Key value for each request. Idempotency keys remain valid for 30 days from creation.
429	Rate Limit Exceeded	Try again later.
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 the trace_id when contacting TrueLayer Support
If you experience an error when integrating our Payments API, you will receive a trace_id in the response. Store this.
If you need to contact Support, include the trace_id to help us identify your request.

Unauthenticated

Either the Authorization or Tl-Signature headers are missing from the HTTP request, or have been sent with an invalid value.

Check the authorisation requirements of the endpoint, and send an appropriate token and signature (if applicable) in the headers.

{
  "type": "https://docs.truelayer.com/docs/error-types#unauthenticated",
  "title": "Unauthenticated",
  "status": 401,
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "detail": "A Bearer token must be provided in the Authorization header."
}

{
  "type": "https://docs.truelayer.com/docs/error-types#unauthenticated",
  "title": "Unauthenticated",
  "status": 401,
  "detail": "Invalid header `Tl-Signature`. Invalid signature",
  "trace_id": "96ce50247f87f540bb2d86771b3728b8"
}

Forbidden

The token does not have permission to perform the requested operation.

If using an access_token from our authentication endpoint, this could mean that the token does not have the required scope(s) required by the endpoint.

If using a resource_token, it could be that you are trying to access a resource other than the one the token was issued for.

{
  "type": "https://docs.truelayer.com/docs/error-types#forbidden",
  "title": "Forbidden",
  "status": 403,
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "detail": "The token used for Authorization is not unauthorized to perform the request."
}

Invalid Parameters

One or more fields in the request body or headers were invalid.

The errors field included in the response will specify the JSON path of the request body fields or header names that were invalid, alongside at least one description of the error for each invalid field.

{
  "type": "https://docs.truelayer.com/docs/error-types#invalid-parameters",
  "title": "Invalid Parameters",
  "status": 400,
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "detail": "The request body was invalid.",
  "errors": {
    "beneficiary.type": [
      "Must be either merchant_account or external_account"
    ]
  }
}

Invalid State

The requested operation is not valid, given the current state of the resource.

This can occur if, for example, the next authorisation action for a payment is to redirect, but instead an attempt is made to submit the provider selection action.

{
  "type": "https://docs.truelayer.com/docs/error-types#invalid-state",
  "title": "Invalid State",
  "status": 400,
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "detail": "Status of the payment does not allow this action to be executed."
}

Not Found

The requested resource cannot be found. This can occur if an incorrect payment ID is used in the request path.

{
  "type": "https://docs.truelayer.com/docs/error-types#not-found",
  "title": "Not Found",
  "status": 404,
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "detail": "Payment could not be found."
}

Concurrency Conflict

Another request has been made against the same resource, at the same time, that conflicts with the current request.

{
  "type": "https://docs.truelayer.com/docs/error-types#concurrency-conflict",
  "title": "Concurrency Conflict",
  "status": 409,
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "detail": "The resource is already used by another request."
}

Idempotency Key Concurrency Conflict

Another request using the same Idempotency-Key header value is currently in progress. This could be because you have retried a request due to not receiving a response, but the original request handling has not yet completed on the server.

{
  "type": "https://docs.truelayer.com/docs/error-types#idempotency-key-concurrency-conflict",
  "title": "Idempotency-Key Concurrency Conflict",
  "status": 409,
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "detail": "The Idempotency-Key value is being used for a concurrent request."
}

Idempotency Key Reuse

The Idempotency-Key header value has already been used with a different request payload. Each request must have a unique value for the idempotency key. The validity period of an idempotency key is 30 days.

{
  "type": "https://docs.truelayer.com/docs/error-types#idempotency-key-reuse",
  "title": "Idempotency-Key Reuse",
  "status": 422,
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "detail": "The Idempotency-Key value has already been used for a different request."
}

Rate Limit Exceeded

Too many requests have been made within too short a time frame, so the current request has been rejected.

{
  "type": "https://docs.truelayer.com/docs/error-types#rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "detail": "Too many API requests have been received within the allowed time frame."
}

Provider Error

The request has failed due to an issue contacting an external provider. This can occur when a bank is experiencing some downtime.

{
  "type": "https://docs.truelayer.com/docs/error-types#provider-error",
  "title": "Provider Error",
  "status": 502,
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "detail": "Provider is temporarily unavailable, please retry."
}

Unknown Error

An unexpected error has occurred. Try again, or contact Support if the problem continues.

{
  "type": "https://docs.truelayer.com/docs/error-types#unknown-error",
  "title": "Unknown Error",
  "status": 500,
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "detail": "An error occurred. Please contact customer support."
}

📘

🚧Include the trace_id when contacting TrueLayer Support

Unauthenticated

Forbidden

Invalid Parameters

Invalid State

Not Found

Concurrency Conflict

Idempotency Key Concurrency Conflict

Idempotency Key Reuse

Rate Limit Exceeded

Provider Error

Unknown Error

🚧
Include the `trace_id` when contacting TrueLayer Support