Errors

Every non-2xx response from the Lucerna API uses the same JSON shape — whether you called the Waitlist API yourself or an SDK surfaced it through onError:

{
  "code": "invalid_request",
  "message": "entries: Array must contain at least 1 element(s)"
}

• code — a stable, machine-readable string. Branch on this.
• message — a human-readable explanation. It may change; don't parse it.

Check the HTTP status code first, then code for the specifics.

Status codes

Status	code	Meaning
400	invalid_request	The request body or path parameter failed validation. message names the offending field.
401	unauthorized	The API key is missing, invalid, or revoked. See Authentication.
403	forbidden	The key lacks the required grant, or the waitlist rejects this signup by policy.
404	not_found	The waitlist, gate, or invite code doesn't exist.
410	expired / revoked	The invite code is no longer redeemable. (accept only)
429	rate_limited	Too many requests — slow down and retry with backoff.
500	internal_error	Something went wrong on our side. Safe to retry.

SDKs handle this for you

The Gates and Identity SDKs never throw an API error into your code. Reads fail open (flags false, switches alive, variants null), transient failures are retried with backoff, and anything worth knowing is reported through the onError callback you pass at construction. The one exception: ready() rejects on 401/403 so a bad key fails loudly at startup.

The rest of this page is for direct HTTP callers.

Handling errors

JavaScript

const res = await fetch(url, options);

if (!res.ok) {
  const { code, message } = await res.json();

  switch (code) {
    case "unauthorized":
    case "forbidden":
      throw new Error("Check LUCERNA_SERVER_KEY and its grants");
    case "invalid_request":
      throw new Error(`Bad request: ${message}`);
    case "rate_limited":
    case "internal_error":
      // Transient — retry with exponential backoff.
      break;
    default:
      throw new Error(`${code}: ${message}`);
  }
}

Retrying safely

The write endpoints are idempotent by design, so 429 and 500 responses are safe to retry with backoff:

• Capturing signups is idempotent by email — retries never create duplicates (already-present emails count as skipped).
• Accepting an invite returns 200 again for an already-accepted code.
• Identity syncs and Gates exposure events are deduplicated server-side.