Error codes

All errors follow the same envelope:

{
  "error": {
    "code":    "activation_limit_exceeded",
    "message": "This license key has reached its activation limit (3 of 3 devices).",
    "details": { "limit": 3, "used": 3 },
    "help":    "https://docs.lizen.dev/api/errors"
  }
}

Error reference

HTTP	Code	Description	Action
400	invalid_request	Malformed request, missing or invalid field	Fix the request body
401	authentication_failed	Missing, invalid, or revoked API key	Check your API key
403	forbidden	API key lacks the required scope	Use a key with the correct permissions
403	account_suspended	Account has been suspended	Contact support@lizen.dev
404	not_found	Resource does not exist	Check the ID
409	conflict	Resource already exists (e.g. duplicate product slug)	Change the slug
422	key_revoked	License key has been revoked	Show user a message; direct to support
422	key_expired	License key has expired	Prompt renewal
422	activation_limit_exceeded	Key has reached its device limit	Direct user to deactivate a device at the license portal
422	plan_limit_exceeded	Account has reached its plan’s resource limit	Upgrade plan
429	rate_limited	Too many requests	Respect retry_after (seconds) in the response
500	internal_error	Unexpected server error	Retry with exponential backoff; check status.lizen.dev

Handling errors in the SDK

import { Lizen, PlanLimitError, RateLimitError } from '@lizen/sdk';

const lizen = new Lizen({ apiKey: process.env.LIZEN_API_KEY! });

try {
  await lizen.keys.create({ productId: 'prod_abc', plan: 'pro' });
} catch (err) {
  if (err instanceof PlanLimitError) {
    // Account hit the key limit — prompt upgrade
    showUpgradeBanner();
  } else if (err instanceof RateLimitError) {
    // Back off and retry
    await sleep(err.retryAfter * 1000);
  } else {
    throw err;
  }
}

Validation errors

Validation errors ({ valid: false }) are not HTTP errors — they return 200 with valid: false and a reason field. See Validate a key for the full list.