Start from the response, not the story
A customer’s description of a licensing problem is rarely precise. The API’s response is. Ask for the exact text the app shows, because the app should be showing the server’s error string, and every string below points at one cause.
The eight cases
These responses come from Clavem’s API reference and from calls I made to the live API with its public demo key, as of 19 November 2026.
| Customer sees | HTTP | Cause | Fix |
|---|---|---|---|
license_key not found. |
404 | The key does not exist: a typo, a missing hyphen, or a key from another product | Check the key against the one in the purchase email |
This license key has reached the activation limit. |
400 | Every device seat is in use and this device is not one of them | Free a device, or raise the limit |
This license key has expired. |
200, valid: false |
expires_at has passed, or the subscription ended |
Renew, or move the date forward |
This license key has been disabled. |
400 on activate, valid: false on validate |
You disabled it, or its order was fully refunded | Enable it if that was a mistake |
instance_id not found. |
404 | The key is fine but this device’s activation was removed | Activate again |
Too many requests. Try again in a minute. |
429 | Rate limit: 120 per minute per IP address, 60 per minute per key | Wait a minute, and check for a loop in the app |
| A generic message | 503 | Temporary failure on the service’s side | Retry after a few seconds |
license_key: Invalid input: expected string, received undefined |
400 | The app sent no key | An app bug |
Real responses for two of them:
{"valid":false,"error":"license_key not found."}
{"valid":false,"error":"instance_id not found.",
"license_key":{"id":1,"status":"active","key":"S1GNE-TDEM0-7K4QX-9WZ2P-H5RB8","activation_limit":3,"activation_usage":1,"...":"..."},
"instance":null,"meta":{"...":"..."}}
Notice the second one. It says the key exists and is active, and the device does not. A support agent reading only valid: false would say the license is bad. The right answer is “this computer lost its activation, activate again”.
Which typos the API forgives
Typing a 25-character key is where most “not found” errors begin. I validated the demo key with eight variations to see what the live service accepts:
| What was sent | Result |
|---|---|
| The exact key | Valid |
| All lowercase | Valid |
| Letter O in place of zero | Valid |
| Letter I in place of one | Valid |
| Letter L in place of one | Valid |
| Spaces before and after | Valid |
| Hyphens removed | license_key not found. |
| One character changed | license_key not found. |
Clavem’s documentation says keys it generates forgive the usual misreadings: I and L read as 1, O as 0 and U as V, with capitals ignored and surrounding whitespace trimmed. Imported keys, such as Lemon Squeezy UUIDs, match as written, lower-cased. The one thing it will not repair is missing hyphens, so if your app has a key field, strip spaces and show the key in groups as the customer types. You can also add hyphens in the app before sending when the length fits.
The lookup that answers most tickets
Ask for the email address the customer bought with, then look the license up. In the dashboard that is a search. With the management API:
curl "https://clavem.io/v1/admin/licenses?email=ada@example.com" \
-H "Authorization: Bearer sk_clavem_..."
The response lists their licenses with status, device limit and usage. Open one, and the detail includes its devices with names, creation times and last-seen times. That is usually enough to see the problem:
| You see | Diagnosis |
|---|---|
activation_usage equal to activation_limit |
Device limit reached. The device list shows which machines hold seats |
Status expired and subscription_id set |
The subscription lapsed. Check Stripe for a failed payment |
Status disabled |
A refund or a manual disable. Check the order |
Status inactive |
Issued and never activated. The customer has not entered the key yet |
| The key does not appear under their email | They bought under another address, or the purchase was never mapped to a product |
If a Stripe purchase produced no license at all, the cause is usually a product that is not mapped, a checkout with no email address, or a delayed payment that has not settled. The event log records unmapped purchases.
Replies you can adapt
Device limit reached. “Your key is active on three computers, and that is the limit. You can free one at (your device page link) by entering your key, then activate the new machine. If you would like a higher limit, reply and I will look at it.”
Not found. “The app says it cannot find that key. Please copy it again from your purchase email, including the hyphens. If it still fails, tell me the email you bought with and I will check.”
Expired subscription. “Your subscription ended on the date shown, so the license expired. Renew here (your renewal link) and the same license starts working again once the payment is processed, with no new key.”
Disabled after refund. “Your order was refunded, so the license was disabled. If that was not what you expected, reply and I will check the order.”
Do not ask for the full license key in an email thread when the purchase email is enough. A key is a credential for as long as the license is valid.
When the fix is on your side
Three failure patterns are bugs or design problems in your app:
- Everyone sees “not found”. The app is sending the wrong field or the wrong hostname. Compare a failing request with the example in the API reference.
- Paying users see “needs connection”. Your offline fallback is stricter than the 14-day token window, or the app treats a rate limit as a failure.
- A burst of limit errors after an update. The new version changed how it builds the fingerprint, so existing devices look new and take extra seats. Keep the fingerprint stable across versions. See machine fingerprinting pitfalls.
Read the message your app shows next to the server’s error string. If the app swallows the string and says “invalid license”, you have made your own support work harder.
Where self-service ends
Device management needs no account. A customer enters the key on the device page, sees where it is active and removes a device. The order page keeps the key and the downloads together. Link both from your help page and from the key email. That removes the largest group of requests, which is “I got a new computer”.
Doing this with Clavem
The dashboard shows each license with its devices, status and history, and the management API gives you the same lookup from your own tools. Clavem does not run your support inbox. The lost license keys article covers the case where the customer cannot find the key at all.
Questions
What should I ask a customer who says their key does not work?
Ask for the exact error text on the screen and the email address they bought with. Avoid asking for the full key in an email thread. With the email you can look up the license, read its status and device list, and see the cause in seconds.
Why does a key pasted without hyphens fail?
Clavem matches keys without regard to capital letters and forgives common misreadings, but it does not add missing hyphens. A key pasted without them came back as not found in a test. Ask the customer to paste it as it appears in the email.
How do I free a device for a customer?
Customers can remove their own devices on the device page by entering their key, with no account. You can also see the devices in the dashboard or by reading the license through the management API.