Common embed error codes and messages

When a secure embed encounters an error, an outbound workbook:error event is emitted. You can configure your host application to listen for the workbook error events emitted and display one or more custom error messages depending on the error code.

This document lists possible error codes that might be emitted from a secure embed which you can use to troubleshoot the root cause of an error and add custom handling to your host application code.

📘

For error messages associated with secure embed URLs signed with client credentials, see Secure embed error code reference.

General error codes

These error codes can be emitted while a user interacts with the embedded content.

Error codeDescriptionPossible causes
EEXISTDuplicate record detected.User or team already exists.
EPERMThe requested operation is not permitted.User does not exist in Sigma and automatic user creation is disabled.
ESTALEStale object.The workbook page, or element might have been deleted or archived, or the connection used by the embedded content was archived.
ENOENTObject does not exist.Workbook is not found or the embed user is deactivated.
EACCESPermission denied.The embedded workbook is not shared or no longer shared with the user, or the user does not have a required permission enabled on their assigned account type.
EINVALInvalid argument.The embed URL contains a URL parameter that doesn't exist, the format of the URL is incorrect, or the JWT is expired.
ETIMEDOUTRequest timed out.A query sent to the warehouse timed out, including an export request. The warehouse is overloaded.
NETWORKUnable to connect to Sigma.Your local network is unavailable or a firewall or browser extension is preventing access to Sigma.
UNKNOWNDefault API error message for all other errors.Some other error.

Other error messages

Some error messages do not return a code, but display a message to the user:

Error messageCauseNext step
Session expired. Reload the page.Session length has been exceeded.To avoid this error, consider using a timer in your code to either display a refresh option or auto-refresh the embed for your users before the session length specified with the exp JWT claim is reached.
You don't have permission to access this page.Invalid clientID, or other causes.Validate that your client ID is passed to the embed correctly and is active.

Validate that the user or team is granted access to the embedded content in Sigma.

Validate that the user is active in Sigma.
You don't have permission to access this page. Cannot update account type for internal users.Internal users can't update optional claims in the JWT URL. Modify the client-side API generating your JWT URL to not pass optional claims, such as first_name, last_name, user_attributes, teams or account_type.
You don't have permission to access this page. Invalid sub field in payload.The email address in the sub claim of the JWT is invalid.Validate the email address entered in the claim is correct, and doesn't contain any white space.