Error reference

Read them with client.error_code() and client.error_message(). Codes are part of the contract and will not change; messages are human copy and may be reworded.

Returned in plaintext

These are raised before the envelope can be decrypted, so they arrive unsigned. A correct client treats any unsigned response as a hard failure and never as success.

Code	Meaning and fix
UNKNOWN_APP	The application id does not exist. Re-download the SDK.
BAD_SIGNATURE	The secret does not match, or the envelope was edited in flight. Re-download the SDK rather than hand editing the config.
RATE_LIMITED	Too many requests from this IP. Back off; the response says for how long.
INVALID_ENVELOPE	A field is missing or malformed. Almost always a bug in a hand written client.

Session and transport

Code	Meaning and fix
CLOCK_SKEW	The timestamp is outside the application tolerance. Sync the machine clock; do not widen the window as a workaround.
REPLAY_DETECTED	That nonce was already used. Generate a fresh random nonce per request.
SESSION_EXPIRED	The session lapsed. Call init and login again.
NOT_AUTHENTICATED	The action needs a logged in session. Call login first.
ALREADY_AUTHENTICATED	This session already logged in. Use a new session.
INVALID_PAYLOAD	A field failed validation, for example a chunk index out of range.

Application state

Code	Meaning and fix
APP_DISABLED	You disabled the application. Carries your status message.
APP_PAUSED	The application is in maintenance.
VERSION_MISMATCH	The client version differs from the application version. Carries the update URL and message when set.

License

Code	Meaning and fix
INVALID_KEY	No such key for this application. Note that keys are per application.
KEY_BANNED	You banned it. Carries the reason so support can explain it.
KEY_EXPIRED	The subscription elapsed.
KEY_REVOKED	Permanently withdrawn.
HWID_LIMIT	The key is bound to its device limit. Reset devices on the key to rebind.
HWID_REQUIRED	The application enforces hardware locking but the client sent no hardware id.
MAX_USES_REACHED	The login budget is exhausted.
CONCURRENT_SESSION_LIMIT	Too many live sessions for this key. Either the customer is sharing it or an old session has not expired.
LOGIN_THROTTLED	Too many failed logins from this IP for this application.

Self service hardware reset

Code	Meaning and fix
HWID_RESET_DISABLED	The owner did not enable self service resets for this application.
HWID_RESET_COOLDOWN	Reset too soon. Carries retry_after in seconds and available_at.
HWID_RESET_LIMIT	The key used its lifetime allowance. Only you can clear it now.
HWID_RESET_THROTTLED	Too many reset attempts from this IP.
HWID_RESET_WOULD_EXPIRE	The time charged per reset exceeds what the key has left, so nothing was changed. Carries penalty and remaining in seconds.

Blacklist and files

Code	Meaning and fix
IP_BLACKLISTED	The address is blocked for this application.
HWID_BLACKLISTED	The device is blocked.
FILE_NOT_FOUND	No enabled file with that JSON key in the active release, or the key level is below the release minimum. The two cases are deliberately not distinguished.
FILE_UNAVAILABLE	Server side: the stored blob failed its integrity check or could not be read. Check the activity log for file.error and re-upload.
VAR_NOT_FOUND	No enabled variable with that name at this key level.

Raised by the SDK itself

These never come from the server; the client produces them locally.

Code	Meaning and fix
NETWORK_ERROR	WinHTTP could not reach the endpoint. Check DNS, firewall and TLS.
PROTOCOL_ERROR	The response was not a valid envelope, or metadata was missing. Often a proxy rewriting the body.
CRYPTO_ERROR	A CNG call failed, or the response tag did not verify. Treat as an attack until proven otherwise.
FILE_CORRUPT	A downloaded payload failed its size or SHA-256 check. The SDK clears the buffer rather than hand you bad bytes.
PIN_MISMATCH	Certificate pinning is on and the server public key did not match.
NOT_CONFIGURED	The config is missing an endpoint, application id or secret.