Troubleshooting

Symptom → cause → solution. For the basics on error codes, see the API Getting Started page; common questions are answered in the FAQ.

Sign-in fails or the account is locked

Cause. Either incorrect credentials, or the account is locked for 15 minutes after 5 failed attempts (brute-force protection). A disabled account also can’t sign in.

Solution. Wait 15 minutes and try again, or have an administrator lift the lock or reset the password (Reset your password). Via the API, the lock or deactivation shows up as 403, incorrect credentials as 401.

The 2FA code isn’t accepted

Cause. Usually a clock drift on the device (TOTP codes are time-based), an already-expired code, or the wrong authenticator entry. Via the API this shows up as 428 (2FA active, but totp_code is missing) or 401 (code incorrect).

Solution. Enable automatic time sync on the device, wait for a fresh code, and enter it promptly. No more access to the authenticator? Sign in using a second registered device. If you have no device left at all, an administrator resets your 2FA — there are no backup codes. See Set up 2FA.

Module not visible or grayed out

Cause. Three possible reasons, to check in this order:

1. Plan. The module belongs to a higher plan (many modules from Professional, Provisioning/Webhooks from Elite).
2. Disabled instance-wide. A Super Admin has turned the module off globally.
3. Role. Your role doesn’t have permission for that area.

Solution. Check the plan and limits (Understanding limits); enable the module if needed (Enabling modules); check the role (Roles & Permissions). A locked module shows an upgrade notice in the interface.

401 on API calls

Cause. Not authenticated — the token is missing, mistyped, expired, or revoked.

Solution. Set the header exactly: Authorization: Bearer inv_…. Check the token prefix and validity; if in doubt, create a new one (Creating a token). The token is shown in plain text only once, at creation — a lost token can’t be retrieved, only replaced.

403 on API calls

Cause. Authenticated, but not allowed. Three categories to distinguish:

1. Limit reached — for example "Asset limit reached (2500) for the 'professional' plan…".
2. Module not in the plan — feature gating (for example webhooks without Elite).
3. Role/scope insufficient — write access attempted with a read token, or without a matching role.

Solution. If capacity is the issue, clean up old/deleted records (the recycle bin still counts!) or upgrade the plan; if a feature is missing, check the plan/module (Understanding limits); for scope issues, use a token with write (API Getting Started).

422 validation error

Cause. The payload is incomplete or has the wrong type — for example an empty name, an unknown asset_type, or the wrong date format.

Solution. The response names the field and reason under detail — fix exactly that field. Allowed values are listed in the API Reference for the relevant endpoint.

429 — too many requests

Cause. The rate limit (default 60 requests/minute per IP, especially on auth endpoints) has been exceeded.

Solution. Read the Retry-After header and implement backoff; stagger parallel loops. For bulk operations, use pagination (page_size up to 100) instead of many individual calls.

CSV import: rows are missing

Cause. Invalid rows are silently skipped (only noted in the log), without an error code. Typical triggers: an empty name, an unknown asset_type, or an empty cell in a typed column (date/number/enum) — the latter invalidates the entire row.

Solution. The result message reports the number of skipped records. Make sure the required columns asset_type (valid value) and name (not empty) are filled in, leave typed columns empty or fill them correctly, then re-import the skipped rows. Full walkthrough: CSV import. Careful: re-importing rows that already exist creates duplicates (there’s no duplicate detection).

Webhook isn’t received

Cause. In production, only asset.created is fired — nothing (yet) for other actions. There’s also no automatic retry: every event is delivered at most once (10 s timeout); a slow or briefly unreachable receiver misses it.

Solution. Check the expected event (Events); make sure the receiving endpoint responds quickly (< 10 s) with 2xx; check the delivery log (recent deliveries) and re-fetch missed data via the API (Errors & retries). If “something arrives, but verification fails,” check the X-Webhook-Signature: sha256=… signature against the raw body (Verifying the signature).

SSO button doesn’t appear

Cause. Email discovery only applies to the exact email address of an already existing account (not per domain). New users therefore don’t see a “Sign in with …” button.

Solution. Have the account created first; detection then kicks in. Alternatively, use the provider’s direct start link. Setup and behavior: Email discovery and Setting up SSO.

New license isn’t recognized

Cause. The product license is not uploaded in the interface — it’s stored as the environment variable LICENSE_KEY — and only takes effect after a server restart.

Solution. Enter LICENSE_KEY completely (on a single line) in .env, restart Notory, then check the tier under Administration → License and set the license tier per tenant. Guide: Installing a license.

QR code or image won’t load

Cause. The QR endpoint (/api/v1/assets/{id}/qr) only returns a PNG with valid authentication — a request without a bearer token or session gets 401.

Solution. Send the Authorization header for programmatic requests; in the interface, use the “Download QR Code” action in the asset detail view. Scanning and QR usage: Scanning an asset QR code.

Didn’t find it?

The search at the top (Ctrl + K) searches all guides. For anything else, support is available via notory.io.