Console

Payments API errors

All Payments v3 error codes and types.

Suggest Edits

📘

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.

CodeTypeWhat to do if you see this error
401UnauthenticatedCheck the authorisation requirements of the endpoint, and send an appropriate token and signature (if applicable) in the headers.
403ForbiddenIf 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.
400Invalid ParametersCheck 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.
400Invalid StateCheck 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.
404Not FoundCheck your payment ID value in the request path.
409Concurrency ConflictThe resource is already used by another request.

Try again later.
409Idempotency-Key Concurrency ConflictCheck if there's another request using the same Idempotency-Key header value currently in progress.
422Idempotency-Key ReuseUse a unique Idempotency-Key value for each request.
429Rate Limit ExceededTry again later.
502Provider ErrorTry again, or wait for the provider to be available again and retry.
500Unknown ErrorTry 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 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

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 6 hours.

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

Updated 10 months ago

Next steps