Skip to main content
LicentricDocs
DashboardLog in

Resources

Troubleshooting

Common issues and their solutions when working with the Licentric API.

Validation Codes

When a license validation fails, the response includes a code field explaining why. Here are the most common codes and how to resolve them.

FINGERPRINT_NOT_FOUNDDevice not activated

Cause: The fingerprint provided during validation does not match any activated machine for this license.

Solution: Call the activate endpoint first to register the device, then retry validation with the same fingerprint.

MACHINE_LIMIT_EXCEEDEDToo many devices

Cause: The license has reached the maximum number of activated machines allowed by its policy.

Solution: Deactivate an existing machine to free up a slot, or increase the maxMachines limit in the policy.

NOT_FOUNDInvalid license key

Cause: The license key does not exist or was mistyped.

Solution: Verify the key for typos. Ensure you are using the correct environment (test keys do not exist in live, and vice versa).

HEARTBEAT_REQUIREDDevice needs to check in

Cause: The policy requires heartbeats, and the device has not sent one within the required interval.

Solution: Call the heartbeat endpoint for the machine. Implement a periodic heartbeat loop (e.g. every 5 minutes).

ENTITLEMENTS_MISSINGRequired features not present

Cause: The validation request specified entitlements that the license does not have.

Solution: Add the required entitlements to the license in the dashboard, or adjust the entitlements check in your application.

EXPIREDLicense has expired

Cause: The license expiresAt timestamp is in the past.

Solution: Renew the license by updating its expiration date. Verify server time is synced to UTC.

HTTP Errors

401 Unauthorized

The request is missing authentication or the credentials are invalid.

  • Verify the API key includes the Bearer prefix in the Authorization header
  • Check that the key has not been revoked or rotated in the dashboard
  • Ensure the environment matches: lk_live_ keys only work in production, lk_test_ keys only in test mode

403 Forbidden

The API key is valid but lacks the required scope for this operation.

  • Check the key’s scopes in the dashboard under Settings → API Keys
  • Add the missing scope (e.g. licenses:write) or create a new key with broader permissions

429 Rate Limited

You have exceeded the rate limit. The response includes a Retry-After header indicating how many seconds to wait.

  • Implement caching for validation results to reduce API calls
  • Use exponential backoff when retrying
  • Consider upgrading your plan for higher rate limits
Exponential backoff
# Python — exponential backoff
import time
from licentric.exceptions import RateLimitError

def validate_with_retry(client, key, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.validate(key)
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(e.retry_after)

Connection Issues

Connection Timeout

  • Check firewall rules allow outbound HTTPS to licentric.com
  • Verify the base URL is correct (no trailing slash, includes protocol)
  • Increase the client timeout if on a slow network
  • Try again — transient network issues resolve on retry

Stale Validation Results

  • Reduce the cache TTL in your application
  • Use webhook-based invalidation to clear the cache when license state changes
  • For critical operations, bypass the cache and validate directly

License Expired but Should Be Active

  • Check that the server’s system clock is synced (NTP/UTC)
  • All timestamps in Licentric use UTC — ensure your comparison is timezone-aware
  • Renew the license by updating the expiresAt field
Still stuck?
Check the API Errors reference for the full list of error codes, or reach out to support with your request ID for debugging.
GlossarySecurity