Docs · Reference
Error codes
One table for every official SDK, the C library and the command line tool: each code comes with a sentence for the person using your software and what you should do
Reading an error
Every failure carries a code from this table. Its HTTP status is the API's, or 0 when no answer arrived at all (no network, too slow, an unreadable answer).
Retry means trying again later, unchanged, may work. Anything else needs a change: another key, a renewal, an update, a setting in the dashboard.
C is the number the C library returns for the code (clavis_errors.h); it never changes.
Every SDK gives the sentence for the end user in English or Vietnamese, so you can show it as it is:
- JavaScripterr.userMessage("vi")
- Pythonerr.user_message("vi")
- C#e.UserMessage("vi")
- C++e.user_message("vi")
- Goe.UserMessage("vi")
- Rusterr.user_message("vi")
- Javae.userMessage("vi")
- Cclavis_error_message(client, "vi")
- CLI--lang vi, error.message
License key
invalid_keyHTTP 403 · C 1
- The person using your software sees
- This license key is not valid · check the key you received
- What to do
- Only clients on the first protocol (CLV1.0) get this code. CLV1.1, spoken by every official SDK, answers invalid_credentials instead so keys cannot be guessed
license_expiredHTTP 403 · C 2
- The person using your software sees
- This license has expired · renew it to keep using the software
- What to do
- Extend the license in the dashboard, or point the customer to the customer portal to renew
license_suspendedHTTP 403 · C 3
- The person using your software sees
- This license is paused · contact the seller
- What to do
- You or a rule suspended this license. Reinstate it in the dashboard when the issue is settled
license_revokedHTTP 403 · C 4
- The person using your software sees
- This license has been revoked · contact the seller
- What to do
- A revoked license never works again. Issue a new key if the customer should keep access
license_already_registeredHTTP 409 · C 5
- The person using your software sees
- This key is already linked to another account
- What to do
- Each key belongs to one account. Check which account holds it under Users, or issue another key
already_redeemedHTTP 409 · C 6
- The person using your software sees
- This key is already on your account
- What to do
- Nothing to do: the account already holds this key. Treat it as success in your software
test_key_disabledHTTP 403 · C 56
- The person using your software sees
- This is a test key and the software is now on sale · use the license key you bought
- What to do
- TEST keys stop working once the app is marked as publicly released (App settings). Issue a regular key
Device
device_limitHTTP 403 · C 7
- The person using your software sees
- This license is already used on its maximum number of devices · free a device first
- What to do
- Raise the device limit in the policy, remove an old device in the dashboard, or let the customer transfer from their old machine
device_blockedHTTP 403 · C 8
- The person using your software sees
- This device is blocked · contact the seller
- What to do
- You or Protect blocked this machine for the app. Unblock it under Devices if that was a mistake
device_revokedHTTP 403 · C 9
- The person using your software sees
- This device was removed from the license · activate again
- What to do
- The device was removed (by you, by a transfer, or after a long silence). Activating again takes a free seat
transfer_limitedHTTP 429 · Retry: yes · C 10
- The person using your software sees
- This license moved machines recently · try again later
- What to do
- The policy limits moves per month and asks for a pause between them; the message says when it opens again. You can move the device yourself from the dashboard
transfer_not_allowedHTTP 429 · C 11
- The person using your software sees
- This license cannot be moved to another machine by itself · contact the seller
- What to do
- The policy does not let customers move their device. Allow it in the policy, or move it for them from the dashboard
Session
session_device_mismatchHTTP 401 · C 12
- The person using your software sees
- Your session belongs to another device · sign in again
- What to do
- A session id was copied to another machine. Start a new session on this one (activate or login)
session_requiredHTTP 401 · C 13
- The person using your software sees
- Please sign in or activate first
- What to do
- Call activate, login or trial before heartbeat, variables or check_updates
session_expiredHTTP 401 · C 14
- The person using your software sees
- Your session has ended · sign in again
- What to do
- Sessions end after an hour without a heartbeat. Send one every few minutes while the software runs, and start a new session when this comes back
session_limitHTTP 403 · C 15
- The person using your software sees
- This license is already running in its maximum number of places · close it elsewhere first
- What to do
- The policy limits sessions running at once. Raise the limit, or let older sessions end (logout ends one at once)
Account
invalid_credentialsHTTP 403 · C 16
- The person using your software sees
- The key or the sign-in details are not valid · check them and try again
- What to do
- A wrong username or password, or a key that is unknown, suspended, revoked or expired: CLV1.1 gives one answer for all of them so keys cannot be guessed, unless this machine already holds a seat on the license. Look the key up in the dashboard; repeated failures slow the device down (too_many_attempts)
username_takenHTTP 409 · C 17
- The person using your software sees
- This username is already taken · choose another
- What to do
- Ask for another username in your sign-up form
user_bannedHTTP 403 · C 18
- The person using your software sees
- This account is banned · contact the seller
- What to do
- You banned this end user. Lift the ban under Users if needed
user_limitHTTP 403 · Retry: yes · C 19
- The person using your software sees
- Sign-ups are full right now · try again later
- What to do
- The app reached the end-user limit of your plan. Upgrade the plan or remove unused accounts
no_licenseHTTP 403 · C 20
- The person using your software sees
- Your account has no license yet · enter a key
- What to do
- The account signed in but holds no key. Ask for a key and call redeem
account_requiredHTTP 403 · C 21
- The person using your software sees
- Please sign in to your account first
- What to do
- redeem needs a session opened with login or register, not with a key
mode_not_allowedHTTP 403 · C 22
- The person using your software sees
- This way of signing in is not available for this software
- What to do
- The app's login mode (key, account, or account plus key) does not allow this call. Change the mode under Sign-in and plans, or call the matching function
too_many_attemptsHTTP 429 · Retry: yes · C 23
- The person using your software sees
- Too many failed attempts · wait a few minutes and try again
- What to do
- Repeated wrong keys or passwords from this device slow it down for a while. Show the message and let the person wait
Trial
trial_usedHTTP 409 · C 24
- The person using your software sees
- This device already used its trial · enter a key to continue
- What to do
- One trial per device and app. Offer your purchase link here
trial_expiredHTTP 403 · C 25
- The person using your software sees
- Your trial has ended · enter a key to continue
- What to do
- Show your purchase link, then activate the key the customer buys
trial_deniedHTTP 403 · C 27
- The person using your software sees
- A trial cannot start on this device
- What to do
- Protect refused the trial (for example a machine that looks reset or virtual). See the app's Protect page
Application
app_not_foundHTTP 404 · C 28
- The person using your software sees
- This software is not set up correctly · contact the seller
- What to do
- The app id is wrong or the app was deleted. Copy it again from the app's Connect page
app_pausedHTTP 403 · Retry: yes · C 29
- The person using your software sees
- This software is unavailable right now · try again later
- What to do
- The app is paused (by you, or for your workspace). Resume it in the dashboard; check for a notice from ClavisAUH
maintenanceHTTP 503 · Retry: yes · C 30
- The person using your software sees
- Down for maintenance · back soon
- What to do
- You put the app in maintenance mode; the message you wrote is in the error. Turn it off in the app's settings
access_blockedHTTP 403 · C 31
- The person using your software sees
- Access is blocked from this location or device
- What to do
- An access rule (country, IP, device) or Protect blocked this request. See Access control and Protect
Updates and builds
update_requiredHTTP 426 · C 32
- The person using your software sees
- Please update the software to keep using it
- What to do
- You set a minimum version above this one. Offer the update (check_updates gives the signed download)
build_blockedHTTP 403 · C 33
- The person using your software sees
- This version can no longer be used · please update
- What to do
- You blocked this release. Customers need a newer build
unknown_buildHTTP 403 · C 34
- The person using your software sees
- This copy of the software is not recognised · download it again from the seller
- What to do
- Strict build checking is on and this build hash was never published. Publish the release, or set buildHash to the published value
invalid_manifestraised by the SDK on the machine · C 53
- The person using your software sees
- The update could not be verified · it was not installed
- What to do
- The release manifest is not signed by this app's key. Never install it; check the app keys your build lists
download_failedraised by the SDK on the machine · Retry: yes · C 54
- The person using your software sees
- The update could not be downloaded · try again
- What to do
- The file host answered with an error. The HTTP status is on the error; links in a manifest expire after a while, so call check_updates again
checksum_mismatchraised by the SDK on the machine · Retry: yes · C 55
- The person using your software sees
- The downloaded update is damaged · it was not installed
- What to do
- The file does not match the SHA-256 in the signed manifest. Download again; if it repeats, the hosted file was replaced
Request (integration)
missing_headersHTTP 400 · C 35
- The person using your software sees
- The software could not reach its license server correctly · contact the seller
- What to do
- A request lacked the CLV1 headers. Use an official SDK, or follow /docs/protocol if you wrote your own client
bad_signatureHTTP 401 · C 36
- The person using your software sees
- The software could not prove who it is · reinstall or contact the seller
- What to do
- The device signature did not verify: a damaged device key file, a proxy changing the body, or a modified client. Protect records it
clock_skewHTTP 401 · Retry: yes · C 37
- The person using your software sees
- Your computer's clock is wrong · set the date and time correctly
- What to do
- The SDKs correct the clock and retry once on their own; seeing this means the clock is far off or keeps jumping
invalid_nonceHTTP 400 · C 38
- The person using your software sees
- The software sent a malformed request · contact the seller
- What to do
- The nonce must be 16 to 64 URL-safe characters. Only custom clients see this
replayed_requestHTTP 409 · Retry: yes · C 39
- The person using your software sees
- The request was refused as a repeat · try again
- What to do
- The same signed request arrived twice. A new attempt carries a new nonce; repeated cases may mean someone replays traffic (Protect records it)
invalid_encodingHTTP 400 · C 40
- The person using your software sees
- The software sent a malformed request · contact the seller
- What to do
- Keys and signatures must be base64url without padding. Only custom clients see this
invalid_jsonHTTP 400 · C 41
- The person using your software sees
- The software sent a malformed request · contact the seller
- What to do
- The body was not valid JSON. Only custom clients see this
validation_failedHTTP 400 · C 42
- The person using your software sees
- Some information was missing or not accepted · check what you entered
- What to do
- A field is missing or out of range (for example a username that is too short). The message names the field
Answer verification
unsigned_responseraised by the SDK on the machine · Retry: yes · C 49
- The person using your software sees
- The license server's answer could not be verified · try again later
- What to do
- The answer carried no signature: something between the software and the API (proxy, fake server) answered. Treat as no answer; the SDK reports it to Protect
unknown_keyraised by the SDK on the machine · C 50
- The person using your software sees
- The license server's answer could not be verified · update the software
- What to do
- The answer was signed by a key the software does not list. After rotating the app key, ship builds that list the new key before switching
invalid_response_signatureraised by the SDK on the machine · C 51
- The person using your software sees
- The license server's answer could not be verified · try again later
- What to do
- The signature did not match the answer: it was changed on the way or forged. Treat as no answer; the SDK reports it to Protect
stale_responseraised by the SDK on the machine · Retry: yes · C 52
- The person using your software sees
- The license server's answer was out of date · check your clock and try again
- What to do
- The answer is too old or too new for this request (a replay, or a clock far off). Retry once the clock is right
Network and server
rate_limitedHTTP 429 · Retry: yes · C 43
- The person using your software sees
- Too many requests · wait a moment and try again
- What to do
- This address sent too many calls. Do not heartbeat more often than every minute, and back off before retrying
internal_errorHTTP 500 · Retry: yes · C 44
- The person using your software sees
- The license server had a problem · try again in a moment
- What to do
- Our side failed. Retry with a growing delay; keep using a valid offline token meanwhile. The request id in the message helps support
network_errorraised by the SDK on the machine · Retry: yes · C 45
- The person using your software sees
- Cannot reach the license server · check your internet connection
- What to do
- No answer arrived (offline, DNS, firewall, TLS). Retry later; a valid offline token lets the software keep working
timeoutraised by the SDK on the machine · Retry: yes · C 46
- The person using your software sees
- The license server took too long to answer · try again
- What to do
- The request passed the SDK's time limit. Retry; raise the timeout option on very slow networks
invalid_responseraised by the SDK on the machine · Retry: yes · C 47
- The person using your software sees
- The license server sent an unreadable answer · try again
- What to do
- The answer was not JSON, often a proxy or captive portal page. Check base_url points at the API
unknown_errorraised by the SDK on the machine · Retry: yes · C 48
- The person using your software sees
- Something went wrong · try again
- What to do
- The server refused without a code (an old proxy or gateway in between). The HTTP status is on the error
How these travel on the wire is in the CLV1 protocol specification