> 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/sdk-error-codes.md).

# SDK error codes

The merchant application may encounter the following SDK error codes if prerequisites are not configured.

## Android

| Error code                             | Use case                                                                                                                         | Recommendation                                                                            |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| AUTHENTICATION\_FAILURE\_CANCEL        | This error is returned when device authentication fails.                                                                         | <ul><li>Display the error message to the end user.</li></ul>                              |
| DEVICE\_AUTHENTICATION\_NOT\_SUPPORTED | This error is returned when biometric authentication is not set up on the device.                                                | <ul><li>Display the error message to the end user.</li></ul>                              |
| CRYPTO\_ERROR                          | This error is returned when there is a keystore issue.                                                                           | <ul><li>Display the error message to the end user.</li></ul>                              |
| INVALID\_PARAMETERS                    | This error is returned when the configuration parameters are not valid.                                                          | <ul><li>Display the error message to the end user.</li></ul>                              |
| INVALID\_DEVICE\_AUTHENTICATION\_PARAM | This error is returned when the `FragmentActivity` parameter is null.                                                            | <ul><li>Display the error message to the end user.</li></ul>                              |
| STORAGE\_ERROR                         | This error is returned when the device authentication method is not found in storage.                                            | <ul><li>Display the error message to the end user.</li></ul>                              |
| TOKEN\_NOT\_BOUNDED                    | This error is returned when the provided token is not bound to the device.                                                       | <ul><li>Display the error message to the end user.</li></ul>                              |
| TOKEN\_ALREADY\_BOUNDED                | This error is returned when the provided token is already bound to the device or pending activation.                             | <ul><li>Display the error message to the end user.</li></ul>                              |
| TOKEN\_DEVICE\_BINDING\_PENDING        | This error is returned when the device binding process is still pending.                                                         | <ul><li>Complete the device binding process.</li></ul>                                    |
| TOKEN\_DEVICE\_BINDING\_DECLINED       | This error is returned when the token device binding is declined.                                                                | <ul><li>Display the error message to the end user.</li></ul>                              |
| INVALID\_IDV\_METHOD                   | This error is returned when the provided ID\&V method is invalid.                                                                | <ul><li>Display the error message to the end user.</li></ul>                              |
| ISSUER\_AUTHENTICATION\_REQUIRED       | This error is returned when issuer authentication is required before the end user can proceed.                                   | <ul><li>Select an ID\&V method using <code>IDVSession.selectIdvMethod()</code>.</li></ul> |
| INVALID\_OTP                           | This error is returned when the input OTP is in an invalid format.                                                               | <ul><li>The OTP must not be null or empty, and must be 8 digits or fewer.</li></ul>       |
| JSON\_PARSING\_ERROR                   | This error is returned when an error occurs while parsing JSON.                                                                  | <ul><li>Display the error message.</li></ul>                                              |
| INVALID\_TOKEN\_ID                     | This error is returned when the Visa Provisioned Token ID provided is null or empty.                                             | <ul><li>Display the error message.</li></ul>                                              |
| KEYSTORE\_ERROR                        | This error is returned when the key is permanently invalidated. For example, the end user enrolls a new biometric (fingerprint). | <ul><li>Display the error message.</li></ul>                                              |
| ATTESTATION\_ERROR                     | This error is returned when an issue occurs while generating the attestation object.                                             | <ul><li>Display the error message.</li></ul>                                              |

## iOS

| Error code                                          | Use case                                                                                                                                                                                                                                                                               | Recommendation                                                                                       |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `TMGError.tokenNotBound`                            | This error is returned when the provided token is not bound to the device.                                                                                                                                                                                                             | <ul><li>Display the error message to the end user.</li></ul>                                         |
| `TMGError.tokenPending`                             | This error is returned when the device binding process is still pending.                                                                                                                                                                                                               | <ul><li>Complete the device binding process.</li></ul>                                               |
| `TMGError.tokenDeclined`                            | This error is returned when the token device binding is declined.                                                                                                                                                                                                                      | <ul><li>Display the error message to the end user.</li></ul>                                         |
| `TMGError.tokenAlreadyBound`                        | This error is returned when the provided token is already bound to the device or pending activation.                                                                                                                                                                                   | <ul><li>Display the error message to the end user.</li></ul>                                         |
| `TMGError.invalidConfigParams`                      | This error is returned when the `TMGClientConfiguration` parameter is not valid.                                                                                                                                                                                                       | <ul><li>Check the implementation details.</li></ul>                                                  |
| `TMGError.invalidRequiredParams`                    | This error is returned when the mandatory parameters are invalid.                                                                                                                                                                                                                      | <ul><li>Check the implementation details.</li></ul>                                                  |
| `TMGError.invalidIdvMethod`                         | This error is returned when the provided ID\&V method is invalid.                                                                                                                                                                                                                      | <ul><li>Display the error message to the end user.</li></ul>                                         |
| `TMGError.invalidOTPMessage`                        | This error is returned when the input OTP is in an invalid format.                                                                                                                                                                                                                     | <ul><li>The OTP must not be null or empty, and must be 8 digits or fewer.</li></ul>                  |
| `TMGError.issuerAuthenticationRequired`             | This error is returned when issuer authentication is required before the end user can proceed.                                                                                                                                                                                         | <ul><li>Select an ID\&V method using <code>PendingBindingSession.selectIdvMethod()</code>.</li></ul> |
| `TMGError.biometricNotSupported`                    | This error is returned when biometric authentication is not set up on the device.                                                                                                                                                                                                      | <ul><li>Display the error message to the end user.</li></ul>                                         |
| `TMGError.authenticationFailure(reason: String)`    | This error is returned when device authentication fails.                                                                                                                                                                                                                               | <ul><li>Display the error message to the end user.</li></ul>                                         |
| `TMGError.authenticationKeyInvalidated`             | This error is returned when the end user changes the biometrics used for authentication. For example, the end user updates Face ID or fingerprint settings. When this error is returned, the cryptographic key pair is no longer accessible, and all tokens are automatically unbound. | <ul><li>Display the error message to the end user.</li></ul>                                         |
| `TMGError.internalError(additionalMessage: String)` | This error is returned when an internal error occurs. The `additionalMessage` provides more detail. This error is not recoverable. Contact Thales support.                                                                                                                             | <ul><li>Display the generic error message to the end user.</li></ul>                                 |
| `TMGError.deviceEnvironmentUnsafe(code: Int)`       | This error is returned when the device environment is potentially unsafe. Check the obfuscated error code with Thales.                                                                                                                                                                 | <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/sdk-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.