liforma docs

Errors

HTTP status codes and error responses.

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

StatusMeaning
400Invalid request body, or IDEMPOTENCY_KEY_INVALID when Idempotency-Key is longer than 256 characters.
401Invalid or missing API key (/v1/sessions)
403Origin not allowed, experience not public, or missing Origin header
404Experience or session not found
409IDEMPOTENCY_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.
429Rate limit or quota exceeded
503Session 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)

StatusMeaning
401Invalid or expired session token

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