falaw.account#

Account health probe.

fal_client swallows the JSON body of its 403s, so a locked-account error looks identical to “wrong API key” or “model is busy.” health_check() makes a tiny, idempotent request to the fal storage endpoint and returns a typed AccountStatus so the caller can distinguish:

account is locked / unverified → AccountStatus.locked is True
bad credentials → AccountStatus.unauthorized is True
everything looks fine → AccountStatus.ok is True
network / unknown error → all flags False, error populated

Use this before a long render to fail fast with a useful message:

from falaw.account import health_check
status = health_check()
if not status.ok:
    raise SystemExit(status.message_for_user())

Functions

health_check(*[, probe_url, timeout_s, api_key])

Probe the fal storage endpoint and return a typed AccountStatus.

Classes

AccountStatus(ok, locked, unauthorized, ...)

Outcome of health_check().

class falaw.account.AccountStatus(ok, locked, unauthorized, status_code, detail, url, error)[source]#

Bases: object

Outcome of health_check().

detail: str#: Server-supplied detail string (best-effort), or ‘’ if unavailable.

error: str | None#: repr of the underlying exception when ok is False and the failure isn’t a recognized lock/unauth (e.g. network error).

locked: bool#: True iff the response indicated a locked / unverified account.

message_for_user()[source]#

Single human-readable line explaining the status. Stable for logging.

Return type:: str

ok: bool#: True iff the account responded without an auth/lock error.

status_code: int | None#: HTTP status from the probe (None if no HTTP exchange happened).

unauthorized: bool#: True iff credentials are missing or invalid.

url: str | None#: If actionable (e.g. billing dashboard), URL the user should visit.

falaw.account.health_check(*, probe_url='https://rest.fal.ai/storage/auth/token?storage_type=fal-cdn-v3', timeout_s=10.0, api_key=None)[source]#

Probe the fal storage endpoint and return a typed AccountStatus.

Parameters:

probe_url (str) – Endpoint to probe. Default is the storage-auth-token endpoint fal_client uses internally; small, idempotent, requires auth.
timeout_s (float) – Network timeout.
api_key (str | None) – Optional override of FAL_KEY. Falls back to a key bound with falaw.using_fal_credentials(), then the env var.

Return type:

AccountStatus

Returns:

AccountStatus with ok=True when the probe succeeded.