Error Handling

UtaError                       (base — catch this for "any SDK failure")
├── UtaConfigError             local: missing or invalid config (client id/secret, redirect URI)
├── UtaDiscoveryError          couldn't fetch the OpenID discovery doc / JWKS
├── UtaAuthError               login flow: state mismatch, user canceled, bad authorize request
├── UtaTokenError              401: code exchange failed, ID-token invalid, or access token expired/revoked
├── UtaPermissionError         403: valid token missing the "entitlements" scope
│   └── UtaServiceNotEnabledError  403: the app hasn't enabled the Hosted sign-in add-on
│                              (a SUBCLASS — catch it BEFORE UtaPermissionError)
├── UtaNotFoundError           404: unknown license key, order ref, or license id (.code says which)
├── UtaOrderProcessingError    202: order is genuine but its license hasn't landed yet — retry
├── UtaLicenseCanceledError    409: can't regenerate a key whose license is terminally gone
└── UtaServerError             5xx from the provider (retriable with backoff)

from usethatapp import (
    UtaError,
    UtaTokenError,
    UtaPermissionError,
    UtaServiceNotEnabledError,
    get_entitlement,
)

def gated_view(request):
    token = request.session.get("uta_access_token")
    if not token:
        return redirect("/login")

    try:
        ent = get_entitlement(token)
    except UtaTokenError:
        # 401: token expired/revoked (or the user signed out). Reconcile and
        # re-authenticate — try refresh() first if you stored a refresh token.
        for k in ("uta_access_token", "uta_sub", "uta_id_token"):
            request.session.pop(k, None)
        return redirect("/login")
    except UtaServiceNotEnabledError:
        # 403: Hosted sign-in is switched off for this app. Nothing the
        # USER does can fix it — no retry, refresh, or re-consent helps.
        # Alert yourself (the developer) and degrade gracefully. Catch
        # this BEFORE UtaPermissionError: it is a subclass, so the scope
        # branch below would swallow it into a re-consent loop.
        logger.error("Hosted sign-in add-on is disabled for this app")
        return render(request, "dashboard.html", {"version": None})
    except UtaPermissionError:
        # 403: valid token, missing the "entitlements" scope.
        return redirect("/login")  # re-consent with openid entitlements
    except UtaError as e:
        # Discovery / server / config failure: log + degrade to free.
        logger.exception("get_entitlement failed: %s", e)
        return render(request, "dashboard.html", {"version": None})

    return render(request, "dashboard.html", {"version": ent.version})

import {
  UtaError,
  UtaTokenError,
  UtaPermissionError,
  UtaServiceNotEnabledError,
  getEntitlement,
} from "usethatapp";

export async function getCurrentPlan(req) {
  const token = req.session.utaAccessToken;
  if (!token) return { state: "logged-out" };

  try {
    const ent = await getEntitlement(token);
    return { state: "ok", ent };
  } catch (e) {
    if (e instanceof UtaTokenError) {
      // 401: expired/revoked (or signed out). Reconcile and re-auth.
      delete req.session.utaAccessToken;
      delete req.session.utaSub;
      delete req.session.utaIdToken;
      return { state: "logged-out" };
    }
    if (e instanceof UtaServiceNotEnabledError) {
      // Hosted sign-in is switched off for this app. Nothing the USER
      // does can fix it — alert yourself and degrade. Check this BEFORE
      // UtaPermissionError: it is a subclass, so the branch below would
      // swallow it into a re-consent loop that can never succeed.
      console.error("Hosted sign-in add-on is disabled for this app");
      return { state: "ok", ent: null };
    }
    if (e instanceof UtaPermissionError) {
      return { state: "needs-scope" };   // re-consent with openid entitlements
    }
    if (e instanceof UtaError) {
      console.error("getEntitlement failed:", e.message);
      return { state: "ok", ent: null }; // degrade to free
    }
    throw e;
  }
}