Error types

Learn about the different types of error codes returned when using our Payments API v3.

Use this page as a guide to the different types of error codes you can come across while integrating with and testing our Payments API. If you're still unable to troubleshoot the problem yourself after checking out the different error code types, you can contact us. When you contact Client Care, include the trace_id from the error response to help us identify your request.

📘

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

Error code types

Check the following table for the types of error codes and relevant actions to take. You'll find details and examples of each error type below the table.

Type

Action to take

Unauthenticated

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

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.

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.

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.

Not Found

Check your payment ID value in the request path.

Conflict

Try again.

Idempotency-Key Concurrency Conflict

Check if there's another request using the same Idempotency-Key header value currently in progress.

Idempotency-Key Reuse

Use a unique Idempotency-Key value for each request.

Provider Error

Try again, or wait for the provider (user's bank) to be available again and retry.

Unknown Error

Try again, or contact Client Care if the problem continues.

Unauthenticated

Occurs if 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."
}

Forbidden

The token sent with the Authorization header 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

Occurs if either 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 the header names, that were invalid, together with 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 authorization 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."
}

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#conflict",
  "title": "Conflict",
  "status": 409,
  "trace_id": "96ce50247f87f540bb2d86771b3728b8",
  "detail": "Another request conflicted with the current request."
}

Idempotency-Key Concurrency Conflict

Another request using the same Idempotency-Key header value is currently in progress. This could occur when 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.

{
  "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."
}

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 customer 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."
}

Did this page help you?