API Errors

Every error code the API can return, the HTTP status it pairs with, what triggers it, and what to do about it. If you hit a code that isn't on this page, treat it as a bug and file an issue — we'd rather fix the docs than have you guessing.

Response shape

Standard errors:

{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": [ /* optional: per-field validation issues */ ]
  }
}

License-validation errors (only on POST /v1/licenses/authorize) use a different envelope so a denial isn't confused with a transport failure:

{
  "ok": false,
  "allow": false,
  "reasonCode": "HWID_MISMATCH",
  "message": "Hardware ID does not match bound device"
}

The status code on a denial is 403, but the body's allow: false is the field you should branch on. See the reason codes below.

How to read this page

• Code — the literal string in error.code. Match on this, not on the message.
• Status — the HTTP status that comes with it.
• Triggered by — what your client did wrong (or what the server is telling you about its own state).
• Fix — the smallest action that gets you past it.
• Retry? — no means retrying the same request will get the same error; fix the request first. yes means transient; back off and try again. clock means retry after a clock fix or fresh nonce.

---

Authentication & authorization

Request signing (license validation)

Validation

All validation errors are no for retry — the server's verdict won't change unless your request changes.

Resource state

Rate limiting

End-user portal

DNS & domains

Server / infrastructure

---

License authorize reason codes

These appear as reasonCode on POST /v1/licenses/authorize when allow: false. The response status is 403. Branch on reasonCode, not status, since the same status can mean a network or signing failure.

Recommended client handling

const result = await response.json();

if (result.allow) {
  return { valid: true, expiresAt: result.effectiveExpiresAt };
}

switch (result.reasonCode) {
  case 'LICENSE_NOT_FOUND':
  case 'PRODUCT_MISMATCH':
    return { valid: false, message: 'Invalid license key' };
  case 'LICENSE_EXPIRED':
  case 'LICENSE_EXPIRED_RELATIVE':
    return { valid: false, message: 'License has expired' };
  case 'LICENSE_REVOKED':
    return { valid: false, message: 'License has been revoked' };
  case 'HWID_MISMATCH':
  case 'HWID_LIMIT_EXCEEDED':
    return { valid: false, message: 'License is bound to a different device' };
  case 'HWID_BLACKLISTED':
  case 'IP_BLACKLISTED':
    return { valid: false, message: 'Access denied' };
  case 'CONCURRENCY_LIMIT_EXCEEDED':
    return { valid: false, message: 'Too many active sessions. Close other instances first.' };
  default:
    return { valid: false, message: result.message || 'Validation failed' };
}

---

Retry guidance

Retry with exponential backoff (start at 1s, double each attempt, jitter, cap at 60s, max 5 attempts):

• 429 RATE_LIMITED / 429 PRODUCT_RATE_LIMITED — honor Retry-After
• 500 INTERNAL — transient
• 503 SIGNING_UNAVAILABLE / 503 RATE_LIMIT_UNAVAILABLE — Redis backing-store hiccup
• 502 / 504 — gateway transient

Do not retry these — fix the request instead:

• 400 (any) — your payload is wrong
• 401 (any) — your credential is wrong
• 403 FORBIDDEN, 403 PERMISSION_DENIED — you don't have access; retrying won't help
• 404 — the resource doesn't exist
• 409 — resolve the conflict (or use a fresh idempotency key)
• 410 GONE — invite expired; ask for a new one

Diagnostic header

Every response includes x-request-id. Capture and log it — when you contact support, that one string lets us pull the exact request out of our logs.

Retry-After is guaranteed on 429

Every 429 response from GeckoGuard sets a Retry-After header (in seconds). You do not need a fallback for the missing-header case — it's always present, on every limiter (per-IP, per-key, per-license, login, signup, forgot-password, TOTP). Default value is 60; longer-window limiters (signup, password-reset) emit the full window length. Honor it as your floor and add exponential backoff on top.