Reference
What each error code means and what to do about it.
Failed requests return a 4xx or 5xx status with a JSON body. Use code in your logic and show or log detail. Include request_id when contacting support.
{
"status": 409,
"code": "activation_limit_reached",
"detail": "Every device slot for this license is in use.",
"request_id": "req_8f3k2..."
}/v1/runtime/validate doesn't return errors for license problems. It returns 200 with data.valid and one of these codes:
| Code | Meaning | What to do |
|---|---|---|
| valid | The license can be used. | Unlock. If in_grace is true, remind them to renew. |
| license_not_found | No such key in this environment. | Ask them to re-enter it. Check you're using the right environment's key. |
| product_mismatch | The key is for a different product. | Ask for the right key. |
| license_not_started | The start date is in the future. | Tell them when it starts. |
| license_expired | Past expiry and the grace period. | Offer a renewal. |
| license_suspended | Paused by you. | Point them to support. |
| license_revoked | Permanently cancelled. | Lock the app. |
| license_superseded | Replaced by a newer license. | Ask for their new key. |
| not_activated | This device isn't activated. | Run activation. |
| device_mismatch | The device fingerprint changed. | Ask them to deactivate and activate again. |
| Code | Status | Meaning |
|---|---|---|
| invalid_request | 400 | The request is malformed. |
| validation_failed | 422 | A field is invalid. meta.errors says which. |
| invalid_api_key | 401 | The key is wrong, revoked, or expired. |
| forbidden | 403 | Your role or key can't do this. |
| insufficient_scope | 403 | The secret key is missing a scope. |
| plan_limit_reached | 403 | You've reached your plan's limit for this item. |
| organization_suspended | 403 | Your organization is suspended. Your customers' apps keep working. |
| license_not_active | 403 | The license is suspended, revoked, or superseded. |
| license_expired | 403 | The license has expired. |
| offline_not_allowed | 403 | The license doesn't allow offline use. |
| not_found | 404 | It doesn't exist, or belongs to another organization or environment. |
| conflict | 409 | Not possible in the current state, such as reinstating a revoked license. |
| idempotency_key_reuse | 409 | That Idempotency-Key was already used for a different request. |
| activation_limit_reached | 409 | Every device slot is in use. |
| not_activated | 409 | Activate the device first. |
| device_mismatch | 409 | The device fingerprint doesn't match. |
| rate_limited | 429 | Too many requests. Wait for Retry-After. |
| internal_error | 500 | Something went wrong on our side. Retry with backoff. |
| service_unavailable | 503 | Temporarily unavailable. Retry with backoff. |
Retry 429 and 5xx responses with exponential backoff (the SDK does this for you). Other 4xx errors will keep failing until you change the request.