Types & errors

1from neuctra_authix import (
2    # client
3    Authix,            # the client
4    NeuctraAuthix,     # alias, matching the JavaScript SDK's class name
5    DEFAULT_BASE_URL,
6
7    # pagination
8    Page, MAX_LIMIT, DEFAULT_LIMIT,
9
10    # keys
11    parse_api_key, mask_key, ParsedKey, PUBLISHABLE, SECRET,
12
13    # errors
14    AuthixError,             # base of everything below
15    ConfigurationError,      # bad client setup — raised before any request
16    NetworkError,            # request never completed
17    AuthixAPIError,          # base for every API error response
18    AuthenticationError,     # 401
19    NoUserSessionError,      # 401, no signed-in user
20    InsufficientScopeError,  # 403, wrong key type
21    PermissionDeniedError,   # 403, not permitted
22    NotFoundError,           # 404
23    ValidationError,         # 400
24    VersionConflictError,    # 409
25    RateLimitError,          # 429
26    ServerError,             # 5xx
27)

1page = authix.get_user_data(user_id=user_id, limit=50)
2
3len(page)          # records in this page
4bool(page)         # False when the page is empty
5page[0]            # index into the records
6for r in page: ...  # iterate them
7
8page.data          # list[dict] — the records
9page.has_more      # bool
10page.next_cursor   # str | None — pass back as `cursor`
11page.total         # records in THIS page, not the total that exist
12page.raw           # the untouched response, if you need a field we do not expose

1AuthixError                    # catch this to catch everything
2├── ConfigurationError         # bad key, missing app_id — no request was made
3├── NetworkError               # timeout, DNS, connection refused
4└── AuthixAPIError             # the API returned an error
5    ├── AuthenticationError            401
6    │   └── NoUserSessionError         401 — endpoint needs a signed-in user
7    ├── InsufficientScopeError         403 — publishable key on a secret route
8    ├── PermissionDeniedError          403 — unverified account, plan limit
9    ├── NotFoundError                  404
10    ├── ValidationError                400
11    ├── VersionConflictError           409 — carries current_version
12    ├── RateLimitError                 429 — carries reset_date
13    └── ServerError                    5xx

1from neuctra_authix import (
2    InsufficientScopeError,
3    NetworkError,
4    NoUserSessionError,
5    RateLimitError,
6    VersionConflictError,
7)
8
9try:
10    authix.update_user_data(
11        user_id=user_id, data_id=data_id, data=changes, version=version,
12    )
13
14except VersionConflictError as exc:
15    # The only error routinely worth retrying. Nothing was written.
16    retry_from(exc.current_version)
17
18except NoUserSessionError:
19    # The session expired or was revoked mid-use.
20    send_to_login()
21
22except InsufficientScopeError:
23    # Our bug, not the user's: this call needs a secret key and belongs
24    # on the server. Log it loudly; never show it to a user.
25    logger.exception("wrong key type for this endpoint")
26    raise
27
28except RateLimitError as exc:
29    # Back off until the quota resets.
30    schedule_retry(after=exc.reset_date)
31
32except NetworkError:
33    # The request may never have arrived — or may have been processed
34    # with the response lost. Treat it as unknown, not as failed.
35    mark_unknown()

1from neuctra_authix import mask_key, parse_api_key, SECRET
2
3parsed = parse_api_key(os.environ["AUTHIX_SECRET_KEY"])
4
5parsed.type      # "secret"
6parsed.env       # "live"
7parsed.prefix    # "sk_live_a1b2c3d4" — not secret, safe to log
8
9if parsed.type == SECRET and running_on_client:
10    raise RuntimeError("secret key must not ship to end users")
11
12# Safe to print anywhere.
13print(mask_key(key))   # sk_live_a1b2c3d4…9f2c