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.

Public auth errors (SDK)

The public auth endpoints (/auth/validate, /auth/heartbeat, and /auth/selfban) return errors as real HTTP status codes with a JSON body of the form {"status": "failed", "error": "<code>"}:

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

The HTTP status code matches the class of failure:

HTTP Status	Error codes
400	`bad_request`, `malformed_request`
401	`invalid_app`, `invalid_key`, `session_expired`, `replay_detected`
403	`blocked`, `app_disabled`, `hwid_mismatch`, `revoke_requires_session`
410	`expired`, `revoked`
429	`rate_limited`, `no_credits`, `app_burn_cap_reached`, `demo_quota_exceeded`
500	`system_error`

Successful responses return 200 with status: "success". Public auth requests are protected by two layers of throttling:

API Gateway stage throttling: burst 200, sustained 100 req/s (default for every route on this API: /auth/validate, /auth/heartbeat, and /auth/selfban)
Application-level per-minute limits on /auth/validate:
- 30/min per IP
- 5/min per license key
Application-level per-minute limit on /auth/heartbeat:
- 6/min per license key

/auth/heartbeat is not IP rate-limited at the application layer, only per-license. The default online check-in interval of 15 minutes is far below the limit; the per-license cap exists to stop runaway loops. Unlimited-seat (shared) licenses are limited per device instead of per key, so a popular shared key is not throttled as one bucket: 5/min per device on /auth/validate and 6/min per device on /auth/heartbeat (a device is the license key plus its HWID). Each endpoint also has a ceiling across all devices on the key: 300/min on /auth/validate and 3000/min on /auth/heartbeat. Validate’s is lower because the client chooses the HWID and every success costs a credit, so the per-key ceiling is what bounds a leaked key. These limits use fixed one-minute windows, so a launch rejected by the 300/min validate ceiling will usually be rejected again if retried within the same minute. Apps that run one shared key across a large fleet that may start all at once should retry login() on rate_limited with exponential backoff for up to about 60 seconds. Additional application limits on /auth/selfban: 10/min per IP (all self-ban requests), and 3/min per license key for pre-session requests that send licenseKey + app credentials. When a validate request exceeds either limit, the response is HTTP 429 with:

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

Successful /auth/validate responses include the X-RateLimit-Remaining header (the lowest of the remaining IP and per-license validate quotas; for shared keys, the per-device and per-key quotas). Successful /auth/heartbeat responses include the same header with the remaining per-license check-in quota (for shared keys, the lower of the per-device and per-key quotas). The official SDKs parse both the HTTP status code and the JSON error field, so 429 responses surface as rate_limited automatically; no special handling is needed in your integration.

Validate errors (`/auth/validate`)

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.
`app_burn_cap_reached`	The app hit its configured hourly/daily credit burn cap.	Show “Authentication service temporarily unavailable. Please try again later.”
`blocked`	The device’s HWID or IP is blacklisted, or not on a required whitelist.	Show “Authentication failed. Contact support.”
`rate_limited`	Too many requests from this IP or license key. Back off and retry after 60 seconds.	Retry with exponential backoff and jitter; wait at least 60 seconds before sustained retries.
`replay_detected`	The nonce has already been used. Generate a fresh nonce for each request (SDKs do this automatically).	This is a developer integration error if you are not using an official SDK.
`bad_request`	The JSON body parsed successfully but failed schema validation (missing fields, invalid types, or a value over its length limit: `appId` 128, `appSecret` 256, `licenseKey` 64, `hwid` 256 bytes as UTF-8, `nonce` 8 to 128, `sessionToken` 4096). Includes a `details` array.	This is a developer integration error.
`malformed_request`	The request body is missing or is not valid JSON.	This is a developer integration error.

Heartbeat errors (`/auth/heartbeat`)

The SDK classification column shows what the official SDKs (1.4.0+) do when a check-in fails with each code:

Definitive: the SDK clears the stored session (as logout() does) and stops check-ins, then calls onFailure("heartbeat_failed", error).
Transient: the SDK keeps the session, calls onFailure("heartbeat_failed", error), and checks in again on the next interval. Once the session TTL has passed, the next transient failure is reported as a definitive session_expired. The SDKs report the grace period ending the same way, except Rust, which reports local session expiry as expired (AuthForgeError::Expired) until its next major release.

A code is only treated as an AuthForge verdict when it arrives in a well-formed error body ({"status": "failed", "error": "<code>"}); anything else is reported as a transient SDK error (see SDK client-side errors). SDKs 1.4.0+ expose the code and classification on the error passed to onFailure; see Check-in and session failure handling for the per-language API.

Error Code	Description	SDK classification	User-facing guidance
`session_expired`	The session token is invalid or has expired, or the app has been deactivated. There is no separate `invalid_session` code.	Definitive	Prompt the user to re-enter their license key or restart the app to log in again.
`revoked`	The license has been revoked since the last heartbeat.	Definitive	Show “This license has been deactivated. Contact support.”
`expired`	The license has expired since the last heartbeat.	Definitive	Show “Your license has expired.” with a renewal link if applicable.
`hwid_mismatch`	This device’s HWID is no longer bound to the license (for example after an HWID reset or seat reassignment). Never returned for unlimited-seat licenses.	Definitive	Show “This license is now in use on another device. Log in again to re-activate, or contact support.”
`blocked`	Since login, the device’s HWID or current IP was blacklisted, or is not on a required whitelist.	Definitive	Show “Authentication failed. Contact support.”
`app_disabled`	The app is paused or the app owner’s account has been suspended.	Definitive	Show “Authentication service temporarily unavailable.”
`malformed_request`	The request body is missing or is not valid JSON.	Definitive	This is a developer integration error.
`no_credits`	The app developer’s account has insufficient credits. Returned on the billing milestone (every 10th successful heartbeat).	Transient	Show “Authentication service temporarily unavailable. Please try again later.” Never expose this to end users. The SDK does not retry immediately; it checks in again on the next interval.
`app_burn_cap_reached`	The app hit its configured hourly/daily credit burn cap during heartbeat billing.	Transient	Show “Authentication service temporarily unavailable. Please try again later.” The SDK checks in again on the next interval.
`demo_quota_exceeded`	The public demo app hit its daily request ceiling (see Try it). Never returned for your own apps.	Transient	The SDK checks in again on the next interval.
`bad_request`	The JSON body parsed successfully but failed schema validation (missing fields, invalid types, or a value over the length limits listed for `/auth/validate`).	Transient	This is a developer integration error.
`system_error`	An unexpected failure occurred while processing the request (for example, credit deduction).	Transient	Show “Authentication service temporarily unavailable.” The SDK checks in again on the next interval.
`rate_limited`	The per-license heartbeat limit (6/min; per device for unlimited-seat licenses) was exceeded.	Transient	This is a developer integration error; keep the check-in interval well above 10 seconds. The SDK retries after 2 seconds, then 5 seconds.

invalid_app is also definitive in the SDKs, but /auth/heartbeat does not return it: a deactivated app yields session_expired.

replay_detected is never returned from /auth/heartbeat. Heartbeats do not enforce nonce replay detection; replay protection is provided by the signed, short-lived session token. Heartbeat rate limiting is per license (6/min; per device for unlimited-seat licenses), never per IP.

Self-ban errors (`/auth/selfban`)

Error Code	Description	User-facing guidance
`revoke_requires_session`	A pre-session self-ban request attempted `revokeLicense: true`. License revoke is only allowed for session-authenticated self-ban requests.	This is a developer integration issue. Retry with `revokeLicense: false`, or call self-ban after login with `sessionToken`.
`invalid_app`	`appId` or `appSecret` is invalid for pre-session self-ban.	Treat as integration/configuration error.
`invalid_key`	The provided pre-session `licenseKey` does not belong to the app.	Treat as integration/configuration error.
`session_expired`	`sessionToken` is missing/invalid/expired for post-session self-ban.	Re-authenticate before requesting self-ban.
`hwid_mismatch`	Post-session only: this device’s HWID is no longer bound to the license (for example after an HWID reset moved the seat to another machine). Nothing is revoked or blacklisted. Never returned for unlimited-seat licenses.	Treat the session as stale: this device no longer holds the seat.
`replay_detected`	Pre-session nonce was reused.	Always send a fresh nonce (official SDKs do this automatically).
`rate_limited`	Too many self-ban requests: 10/min per IP (all modes), 3/min per license key (pre-session requests with `licenseKey` only).	Back off and retry with jittered exponential backoff.
`expired`	License is expired.	Prompt renewal/support workflow.
`revoked`	License was already revoked. Pre-session requests on a revoked license perform no action.	Treat as already-locked state.
`app_disabled`	App or app owner is suspended/paused.	Show generic service-unavailable messaging.
`system_error`	Unexpected server error.	Retry with backoff; alert support if persistent.

SDK client-side errors

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

Error	Description	SDK classification
`nonce_mismatch`	The nonce in the server response doesn’t match the one sent in the request. Possible replay attack.	Transient
`signature_mismatch`	The Ed25519 signature on the server response is invalid. Possible tampering.	Definitive
`unexpected_response`	A failed check-in whose body is not a well-formed AuthForge error (`{"status": "failed", "error": "<code>"}`), for example a proxy or captive portal answering with its own JSON. Never treated as a verdict; the message includes the raw `status` and `error` values.	Transient
`network_error`, `timeout`	Connection failure, DNS failure, or request timeout. The SDK retries once after 2 seconds before failing.	Transient
`http_error_<status>`	An error response whose body is not JSON (for example an HTML error page), for any HTTP status. A JSON error body yields the server’s own code instead.	Transient
`invalid_json_response`	The response body could not be parsed.	Transient

These errors trigger the onFailure callback with the "login_failed" or "heartbeat_failed" reason. Any code an SDK version does not recognize is passed through unchanged and classified as transient.

Offline license file errors (`loginFromFile` / `verifyLicenseFile`)

Verifying a .authforge offline license file is entirely local. Every SDK runs the same checks in this order and reports the first failure through onFailure("offline_login_failed", error) (Go and Rust return typed errors instead):

Code	Meaning	Recommended handling
`bad_armor`	Not well-formed `.authforge` armor (truncated, wrong markers, not base64).	Show “The license file is damaged. Re-download it.”
`bad_signature`	Signature does not verify against any configured public key: tampered file, or minted for a different app’s key.	Show “This file is not a valid license for this product.”
`unsupported_version`	Payload `v` is newer than the SDK understands.	Show “Update the app to use this license file.”
`malformed_payload`	Signed payload is missing required fields.	Treat like `bad_armor`.
`wrong_app`	Valid signature, but minted for a different app id.	Show “This file is not a valid license for this product.”
`expired`	Past the file’s `expiresAt`.	Show “Your offline license expired on . Request a new license file.”
`hwid_mismatch`	File is HWID-bound and this machine’s HWID is not listed.	Show “This license file is for a different machine. Your machine ID is .” and print `getHwid()`.

loginFromFile never terminates the process on its own; display the message and exit from your code.

Best practices for error handling

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.
Let the SDK handle transient check-in errors. Network errors, rate_limited, system_error, no_credits, app_burn_cap_reached, and the other transient codes keep the session, and the SDK checks in again on the next interval. It retries rate_limited (after 2 and 5 seconds) and network failures (once) internally, but deliberately waits for the next interval on no_credits, demo_quota_exceeded, and app_burn_cap_reached; don’t add your own retry loop on top. For login(), retrying network failures a few times with backoff is fine; retrying no_credits is not, since it only clears once you add credits.
Don’t retry definitive errors: revoked, expired, hwid_mismatch, blocked, session_expired, malformed_request, app_disabled, invalid_app, and signature_mismatch (at login, invalid_key is also final for the key the user entered). On a check-in, the SDK has already cleared the session; 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.

​Developer API errors

​Public auth errors (SDK)

​Validate errors (/auth/validate)

​Heartbeat errors (/auth/heartbeat)

​Self-ban errors (/auth/selfban)

​SDK client-side errors

​Offline license file errors (loginFromFile / verifyLicenseFile)

​Best practices for error handling

Developer API errors

Public auth errors (SDK)

Validate errors (`/auth/validate`)

Heartbeat errors (`/auth/heartbeat`)

Self-ban errors (`/auth/selfban`)

SDK client-side errors

Offline license file errors (`loginFromFile` / `verifyLicenseFile`)

Best practices for error handling