Errors

Error format

JSON body uses a nested error object. The same requestId is also returned as the Liforma-Request-Id response header (include it when reporting issues).

{
  "error": {
    "code": "ORIGIN_NOT_ALLOWED",
    "message": "Human-readable description",
    "requestId": "req_…"
  }
}

Session minting

Status	Meaning
400	Invalid request body, or IDEMPOTENCY_KEY_INVALID when Idempotency-Key is longer than 256 characters.
401	Invalid or missing API key (/v1/sessions)
403	Origin not allowed, experience not public, or missing Origin header
404	Experience or session not found
409	IDEMPOTENCY_CONFLICT — Idempotency-Key reused with a different body. IDEMPOTENCY_IN_PROGRESS — same key is still pending (includes Retry-After: 1). Branch on error.code, not status alone.
429	Rate limit or quota exceeded
503	Session minting failed (server error)

Common 403 causes (browser sessions)

• Origin header missing — browser must send origin on cross-origin requests
• Origin not on experience allowlist
• Experience is not marked public

Runtime (SDK internal)

Status	Meaning
401	Invalid or expired session token

Runtime routes (/player/*) are internal to the SDK — integrators typically see these as SDK errors, not raw HTTP.