Common Error Codes
Most ValidonX integration errors fall into a handful of codes — auth, rate-limit, activation, and entitlement — each returned in the standard error envelope with a code, message, and HTTP status. This page is a quick reference for the ones you'll hit while integrating; the full API error-code reference lists every code by domain and documents the envelope format.
Errors you'll hit most often
| Code | HTTP | What it means | Fix |
|---|---|---|---|
AUTH.INVALID_API_KEY | 401 | Missing, invalid, or revoked API key | Check the X-API-Key header and that the key isn't revoked |
AUTH.TOKEN.INVALID_SCOPE | 403 | Bearer token is missing a required scope | Use a token that carries the scope the endpoint needs |
RATE_LIMIT.EXCEEDED | 429 | Too many requests | Back off and honour the Retry-After header |
LICENSE.NOT_FOUND | 404 | License key does not exist | Verify the key value; don't send the bare code |
LICENSE.REVOKED | 403 | License has been revoked | The license is terminal — issue a new one |
ACTIVATION.LIMIT_EXCEEDED | 403 | Maximum activations reached | Deactivate a device or raise the activation limit |
ACTIVATION.INVALID | 400 | Invalid activation, or the license is not active | Re-activate; confirm the license is active first |
ENTITLEMENTS.MISSING | 403 | Feature not on the current plan | Upgrade the plan, or gate the feature client-side |
VALIDATION.FAILED | 422 | Request body validation failed | Inspect details for the offending fields |
Where to go next
- Full API error-code reference → — every code, grouped by domain (AUTH, TENANT, LICENSE, BILLING, ONBOARDING, CATALOG…), plus the error-envelope JSON format.
- Error handling → — how to parse the envelope and branch on
error.codein your client. - HTTP status mapping → — which HTTP status each error domain returns.