Error Handling - Authentication

Error Handling

Error Code	Meaning	Resolution
INVALID_APP_TOKEN_ID	Token ID does not exist	Verify the id parameter; token may have been deleted
INVALID_APP_TOKEN_HASH	HMAC hash mismatch	Recompute SHA256(widget_ks + app_token_value) — verify encoding and confirm input is the exact raw concatenation
APP_TOKEN_NOT_ACTIVE	Token is disabled (status != 2)	Re-enable with appToken.update or create a new token
EXPIRED_TOKEN	Token has passed its expiry timestamp	Create a new token with a future expiry
PROPERTY_VALIDATION_NOT_UPDATABLE	Attempted to change hashType after creation	hashType is immutable — create a new token with the desired hash type
INVALID_KS	The KS used to call the API is invalid or expired	Generate a fresh admin KS via session.start

Retry strategy: For transient errors (HTTP 5xx, timeouts), retry with exponential backoff: 1s, 2s, 4s, with jitter, up to 3 retries. For client errors (INVALID_APP_TOKEN_HASH, INVALID_KS, EXPIRED_TOKEN, validation errors), fix the request parameters before retrying — these require a corrected request to succeed.