> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/merchant-tokenization/sdk-integration/error-management/backend-error-codes.md).

# Backend error codes

The following server error codes may occur during API calls between the Thales SDK and the Thales backend.

## Android

| Error code                            | Use case                                                                                                   | Recommendation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SERVER\_IS\_NOT\_ACCESSIBLE           | This error is returned when the SDK cannot reach the Thales backend due to a network connection issue.     | <ul><li>Display the error message to the end user.</li><li>Tell the end user to check their internet connection.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| SERVER\_ERROR\_CRYPTO\_ERROR          | This error is returned when there is a keystore issue.                                                     | <ul><li>Display the error message to the end user.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| SERVER\_ERROR\_INVALID\_TOKEN\_STATE  | This error is returned when the token state is invalid.                                                    | <ul><li>Display the error message to the end user.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| SERVER\_ERROR\_IDV\_NOT\_AVAILABLE    | This error is returned when the end user selects an ID\&V method that is not available.                    | <ul><li>The Thales backend returns an error when the SDK sends a <code>POST /idv-method</code> or <code>POST /otp</code> request. The SDK returns this error code to the merchant application via the <code>TokenBindingListener.onIssuerAuthenticationError()</code> callback.</li><li>Use <code>IDVSession.getIdvMethods()</code> to get the list of ID\&V methods that can be used to authenticate the end user. If the session remains active, the merchant application can select another ID\&V method using <code>IDVSession.selectIdvMethod()</code>.</li></ul> |
| SERVER\_ERROR\_NO\_SESSION\_FOUND     | This error is returned when the session cannot be found.                                                   | <ul><li>The Thales backend returns an error when the SDK sends a <code>POST /idv-method</code> or <code>POST /otp</code> request. The SDK returns this error code to the merchant application via the <code>TokenBindingListener.onError()</code> callback.</li><li>Call <code>VisaCTFHelper.createBinding()</code> again to create a new session before the end user selects an ID\&V method or verifies the OTP.</li></ul>                                                                                                                                           |
| SERVER\_ERROR\_WRONG\_OTP\_VALUE      | This error is returned when the end user enters the wrong OTP.                                             | <ul><li>The Thales backend returns an error when the SDK sends a <code>POST /otp</code> request. The SDK returns this error code to the merchant application via the <code>TokenBindingListener.onIssuerAuthenticationError()</code> callback.</li><li>The session remains active, and the merchant application can retry or select another ID\&V method using the <code>IDVSession</code> object.</li></ul>                                                                                                                                                           |
| SERVER\_ERROR\_EXPIRED\_OTP           | This error is returned when the end user enters an expired OTP.                                            | <ul><li>The Thales backend returns an error when the SDK sends a <code>POST /otp</code> request.</li><li>The SDK returns this error code to the merchant application via the <code>TokenBindingListener.onIssuerAuthenticationError()</code> callback.</li><li>The session remains active, and the merchant application can retry or select another ID\&V method using the <code>IDVSession</code> object.</li></ul>                                                                                                                                                   |
| SERVER\_ERROR\_RETRY\_LIMIT\_EXCEEDED | This error is returned when the end user exceeds the number of retries allowed.                            | <ul><li>The Thales backend returns an error when the SDK sends a <code>POST /otp</code> request. The SDK returns this error code to the merchant application via the <code>TokenBindingListener.onIssuerAuthenticationError()</code> callback.</li><li>The session remains active, and the merchant application can retry or select another ID\&V method using the <code>IDVSession</code> object.</li></ul>                                                                                                                                                           |
| SERVER\_ERROR\_TOO\_MANY\_REQUEST     | This error is returned when too many requests are sent within a given period of time.                      | <ul><li>Display the error message to the end user.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| SERVER\_ERROR\_RETRYABLE              | This error is returned when the server cannot handle the request due to temporary overload or maintenance. | <ul><li>Display the error message to the end user.</li><li>Retry the request.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| SERVER\_ERROR                         | This error is returned when a server error occurs and it does not fit into any of the above error codes.   | <ul><li>Display the error message to the end user.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

## iOS

| Error code                                                        | Use case                                                                                                                                                                                    | Recommendation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TMGError.serverIsNotAccessible`                                  | This error is returned when the SDK cannot reach the Thales backend due to a network connection issue.                                                                                      | <ul><li>Display the error message to the end user.</li><li>Tell the end user to check their internet connection.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                    |
| `TMGError.serverErrorCryptoError`                                 | This error is returned when there is a keystore issue.                                                                                                                                      | <ul><li>Display the error message to the end user.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `TMGError.serverErrorInvalidTokenState`                           | This error is returned when the token state is invalid.                                                                                                                                     | <ul><li>Display the error message to the end user.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `TMGError.serverErrorIdvNotAvailable`                             | This error is returned when the end user selects an ID\&V method that is not available.                                                                                                     | <ul><li>The Thales backend returns an error when the SDK sends a <code>POST /idv-method</code> or <code>POST /otp</code> request. The SDK returns this error code to the merchant application via the completion handler.</li><li>Use <code>PendingBindingSession.getIdvMethods()</code> to get the list of ID\&V methods that can be used to authenticate the end user. If the session remains active, the merchant application can select another ID\&V method using <code>PendingBindingSession.select()</code>.</li></ul> |
| `TMGError.serverErrorNoSessionFound`                              | This error is returned when the session cannot be found.                                                                                                                                    | <ul><li>The Thales backend returns an error when the SDK sends a <code>POST /idv-method</code> or <code>POST /otp</code> request. The SDK returns this error code to the merchant application via the completion handler.</li><li>Call <code>VisaCTFHelper.createBinding()</code> again to create a new session before the end user selects an ID\&V method or verifies the OTP.</li></ul>                                                                                                                                    |
| `TMGError.serverErrorWrongOTP`                                    | This error is returned when the end user enters the wrong OTP.                                                                                                                              | <ul><li>The Thales backend returns an error when the SDK sends a <code>POST /otp</code> request. The SDK returns this error code to the merchant application via the completion handler.</li><li>The session remains active, and the merchant application can retry or select another ID\&V method using the <code>PendingBindingSession</code> object.</li></ul>                                                                                                                                                             |
| `TMGError.serverErrorExpiredOTP`                                  | This error is returned when the end user enters an expired OTP.                                                                                                                             | <ul><li>The Thales backend returns an error when the SDK sends a <code>POST /otp</code> request.</li><li>The SDK returns this error code to the merchant application via the completion handler.</li><li>The session remains active, and the merchant application can retry or select another ID\&V method using the <code>PendingBindingSession</code> object.</li></ul>                                                                                                                                                     |
| `TMGError.serverErrorRetryLimitExceeded`                          | This error is returned when the end user exceeds the number of retries allowed.                                                                                                             | <ul><li>The Thales backend returns an error when the SDK sends a <code>POST /otp</code> request. The SDK returns this error code to the merchant application via the completion handler.</li><li>The session remains active, and the merchant application can retry or select another ID\&V method using the <code>PendingBindingSession</code> object.</li></ul>                                                                                                                                                             |
| `TMGError.serverErrorTooManyRequest`                              | This error is returned when too many requests are sent within a given period of time.                                                                                                       | <ul><li>Display the error message to the end user.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `TMGError.serverRetryable`                                        | This error is returned when the server cannot handle the request due to temporary overload or maintenance.                                                                                  | <ul><li>Display the error message to the end user.</li><li>Retry the request.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `TMGError.serverError(let httpStatusCode, let additionalMessage)` | This error is returned when a server error occurs and it does not fit into any of the above error codes. The `httpStatusCode` and `additionalMessage` provide more details about the error. | <ul><li>Display the error message to the end user.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.payments.thalescloud.io/merchant-tokenization/sdk-integration/error-management/backend-error-codes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.