Error Codes Reference

Developer API errors

All Developer API errors return a JSON object with an error code and a human-readable message:

{
  "error": "not_found",
  "message": "Resource not found"
}

HTTP Status	Error Code	Description
400	`bad_request`	Invalid or missing request parameters. Check the request body and query parameters.
401	`invalid_api_key`	Missing, malformed, or revoked API key. Verify your `Authorization: Bearer` header.
402	`no_credits`	Insufficient credits to complete the operation. Purchase more credits in the dashboard.
403	`forbidden`	The target app or license doesn’t belong to your account.
404	`not_found`	The license key, webhook, or endpoint doesn’t exist.
429	`rate_limited`	Too many requests. Back off and retry with exponential backoff. Burst limit: 100 req/s, sustained: 50 req/s.
500	`internal_error`	Unexpected server error. Retry the request. If persistent, contact support.

The public auth endpoints (/auth/validate and /auth/heartbeat) return errors inside a 200 HTTP response with status: "failed":

{
  "status": "failed",
  "error": "invalid_key"
}

Error Code	Description	User-facing guidance
`invalid_app`	The App ID or App Secret is incorrect, or the app has been deactivated.	This is a developer configuration error. Show “Authentication failed.”
`app_disabled`	The app owner’s account is suspended.	Show “Authentication service temporarily unavailable.”
`invalid_key`	The license key doesn’t exist or doesn’t belong to this app.	Show “Invalid license key. Please check and try again.”
`revoked`	The license has been revoked.	Show “This license has been deactivated. Contact support.”
`expired`	The license has passed its expiration date.	Show “Your license has expired.” with a renewal link if applicable.
`hwid_mismatch`	All HWID slots are full and the current device’s HWID doesn’t match any bound device.	Show “This license is already in use on another device. Contact support to reset.”
`no_credits`	The app developer’s account has insufficient credits.	Show “Authentication service temporarily unavailable. Please try again later.” Never expose this to end users.
`blocked`	The device’s HWID or IP is blacklisted, or not on a required whitelist.	Show “Authentication failed. Contact support.”
`bad_request`	The request body is malformed (missing fields, invalid types). Includes a `details` array.	This is a developer integration error.

Error Code	Description
`session_expired`	The session token is invalid or has expired. The SDK should re-authenticate.
`revoked`	The license has been revoked since the last heartbeat.
`expired`	The license has expired since the last heartbeat.
`app_disabled`	The app owner’s account has been suspended.
`no_credits`	The app developer’s account has insufficient credits for the heartbeat billing milestone.

In addition to server errors, the SDK may detect issues locally before or after a server response:

Error	Description
`nonce_mismatch`	The nonce in the server response doesn’t match the one sent in the request. Possible replay attack.
`signature_mismatch`	The HMAC-SHA256 signature on the server response is invalid. Possible tampering.
HTTP/network errors	Connection timeout, DNS failure, or non-200 HTTP status. The SDK retries internally before failing.

These errors trigger the onFailure callback with the "login_failed" or "heartbeat_failed" reason.

Never expose internal error codes to end users. Map them to user-friendly messages.
Log the actual error code for debugging, but show generic messages to users.
Retry on transient errors (no_credits from your account, network errors) with exponential backoff.
Don’t retry on permanent errors (invalid_key, revoked, hwid_mismatch) — prompt the user to take action instead.
Handle no_credits gracefully — this is a billing issue on your end, not the user’s problem.

See SDK Best Practices for detailed error handling guidance with code examples.