The triggerActionEvent(), getSessionToken() and getSecureSessionToken() methods report failures in two ways. We recommend handling both.
| Mechanism | Description | How to handle |
|---|---|---|
| Error token strings | The promise resolves with an error string in place of the token | Check the returned value against the documented prefixes before you treat it as a token |
| Thrown errors | The promise rejects with an SdkError, or with a plain Error | try/catch |
On failure, triggerActionEvent() resolves with an actionToken that holds one of the error strings below.
| Prefix | Returned when |
|---|---|
server_error_ | The server rejected the request |
client_error_ | The request could not be built or sent from the browser |
invalid_claimed_user_id_type_ | An unsupported claimedUserIdType was passed |
disabled_sdk_ | The SDK is disabled or was not initialized |
communication_error_ | The request could not reach the server |
unexpected_error_ | Any other failure |
Format: server_error_<actionType>_<httpCode>_'<message>'_<timestamp>
| Error | Description and example |
|---|---|
| 500 - Internal Server Error | Description: Indicates a general server-side failure. This error occurs when the server encounters an unexpected condition preventing it from fulfilling the request. Example: server_error_login_500_Something went wrong_1732723499326 |
| 502 - Bad Gateway | Description: The server received an invalid response from an upstream server while trying to process the request. Example: server_error_login_502_Bad Gateway_1732723499326 |
| 503 - Service Unavailable | Description: The server is currently unable to handle the request due to temporary overload or maintenance. Example: server_error_login_503_Server Unavailable_1732723499326 |
| 400 - Bad Request | Description: The request sent by the client is invalid. Specific causes include: - Invalid request body: The server could not process the request due to malformed syntax. Example: server_error_login_400_Invalid request_1732722021998 - Decryption error: The server failed to decrypt the request payload. Example: server_error_login_400_Decryption failed_1732972138346 -Decompression error: The server failed to decompress the request payload. Example: server_error_login_400_Decompression failed_1732972138346 -Unsupported action type: The request specified an action type not supported by the server. Example: server_error_dummyType_400_Unsupported action type_1732721929594 |
| 401 - Unauthorized | Description: Authentication failed due to missing or invalid credentials. Client ID not supported: The provided client ID is not recognized. Example: server_error_login_401_Client ID is not supported - "zsKFyTytYtZL3hcvQQ7"_1732722263186 |
| 409 - Conflict | Description: The request could not be processed due to a conflict with the current state of the resource. Event already sent: Indicates a duplicate request for an event already processed. Example: server_error_login_409_Request cannot be processed_1732971102156 |
| 429 - Too Many Requests | Description: The client has sent too many requests in a given amount of time and is being rate-limited. Rate limit exceeded: Indicates throttling due to excessive requests. Example: server_error_login_429_ThrottlerException: Too Many Requests_1732721457134 |
Format: client_error_<actionType>_'<message>'_<timestamp>
| Error | Description and example |
|---|---|
| 'fetch' does not exist on window | Description: The JavaScript fetch API is not supported in the current environment. Example: client_error_login_'fetch-api is not supported'_1732723943772 |
| Encryption error (client-side) | Description: The client failed to encrypt the request data. Example: client_error_login_'crypto is not supported'_1732723943772 |
| Unhandled response | Description: The server accepted the request but returned no action token. Example: client_error_login_'Unhandled SDK error. Received eventResponse: ...'_1732723943772 |
| Invalid action type | Description: The client attempted to perform an unsupported or invalid action type. Example: client_error_'invalid action type - dummyType'_1732723943772 |
Format: invalid_claimed_user_id_type_<claimedUserIdType>_<timestamp>
| Error | Description and example |
|---|---|
| Unsupported claimedUserIdType | Description: The claimedUserIdType passed in the action options is not a supported value. Supported values are: email, phone_number, account_id, ssn, national_id, passport_number, drivers_license_number, other. Example: invalid_claimed_user_id_type_username_1754293254357 |
Format: disabled_sdk_<disabledReason>_action_<timestamp>
| Disabled reason | Description and example |
|---|---|
init_not_called | Description: The init function wasn't called. Example: disabled_sdk_init_not_called_action_1754292026552 |
init_failed | Description: SDK initialization failed. Example: disabled_sdk_init_failed_action_1754292839934 |
config_disabled | Description: The SDK was disabled via configuration. Example: disabled_sdk_config_disabled_action_1754293046441 |
invalid_params | Description: The SDK was initialized with invalid parameters. Example: disabled_sdk_invalid_params_action_1754293254357 |
missing_config | Description: The SDK did not receive the configuration, possibly due to blocked requests. Example: disabled_sdk_missing_config_action_1754293254357 |
Format: communication_error_<actionType>_'<message>'_<timestamp>
| Error | Description and example |
|---|---|
| Encryption error - missing public key | Description: The encryption process failed because the required public key is missing. Example: communication_error_login_'Encryption error - missing public key'_1732799565912 |
| Network error | Description: A network error occurred, possibly due to connectivity issues or timeouts. Example: communication_error_login_'Failed to fetch'_1732799565912 |
Format: unexpected_error_<actionType>_<timestamp>
| Error | Description and example |
|---|---|
| Unexpected error | Description: An error occurred that does not fall into any predefined category. Example: unexpected_error_login_1732799565912 |
Some conditions reject instead of returning an error string.
| Condition | Error code | Message |
|---|---|---|
| Either the SDK init was not called, or the call failed | NotInitialized | tsPlatform not initialized |
| When the SDK operation fails on an unhandled error | Unknown |
On failure, getSessionToken() and getSecureSessionToken() resolve with a disabled_sdk_ error string in place of the token.
Format: disabled_sdk_<disabledReason>_session_<timestamp>
| Disabled reason | Description and example |
|---|---|
init_not_called | Description: The init function wasn't called. Example: disabled_sdk_init_not_called_session_1754292026552 |
init_failed | Description: SDK initialization failed. Example: disabled_sdk_init_failed_session_1754292839934 |
config_disabled | Description: The SDK was disabled via configuration. Example: disabled_sdk_config_disabled_session_1754293046441 |
invalid_params | Description: The SDK was initialized with invalid parameters. Example: disabled_sdk_invalid_params_session_1754293254357 |
missing_config | Description: The SDK did not receive the configuration, possibly due to blocked requests. Example: disabled_sdk_missing_config_session_1754293254357 |
unknown | Description: Returned by getSecureSessionToken() only. The SDK is enabled and initialized, but the token could not be produced. Example: disabled_sdk_unknown_session_1754293254357 |
Some conditions reject instead of returning an error string.
| Condition | Error code | Message |
|---|---|---|
| Either the SDK init was not called, or the call failed | NotInitialized | tsPlatform not initialized |
| When the SDK operation fails on an unhandled error | Unknown | |
enableSessionToken is not set to true in the SDK configuration | - | Session token is not enabled |
• NotInitialized = "not_initialized"
Either the SDK init was not called, or the call failed
• Unknown = "unknown"
When the SDK operation fails on an unhandled error