Troubleshooting

not_started means the flow was never entered. Redirect to the url field from the POST /v3/session/ response verbatim — it's an absolute URL on your tenant's flow domain. Never reconstruct it from the session id.

If expires_at has passed, the session moves to expired, not stuck — see session expired immediately. not_started with a future expires_at means the link is valid and simply hasn't been opened.

GET /v3/session/<id>/logs/ returns a chronological event list. No events after create = the applicant hasn't opened the link (resend it). Events that stop mid-flow = they abandoned; the session will move to abandoned or expired on its own.

The destination must be publicly reachable over HTTPS and must pass an SSRF guard that rejects private, loopback, and link-local addresses — you cannot point webhooks straight at http://localhost. For local development, run a tunnel and set its public HTTPS URL in the console. See Testing → webhook development.

Delivery is at-least-once with retries, but the sender's timeout starts at connect — not when your DB write finishes. Return 2xx immediately, then process asynchronously. A handler that does slow work before responding looks "down" and gets retried (and eventually gives up).

Once your endpoint is healthy, resend any delivery from Console → Developers → Webhooks. Nothing is lost as long as the endpoint recovers within the retry window.

An in_review session (AML/PEP hit, low-confidence check, forgery signal) hasn't produced a terminal decision yet, so no approved/declined webhook has fired. It will settle later when an operator resolves it. The absence of a terminal webhook is not a delivery failure.

The signature is HMAC-SHA256(secret, "<t>." + raw_body). If a framework parsed the body into an object before your handler ran and you re-serialize it, whitespace and key order change and every signature fails. Capture the raw bytes before any JSON parsing — in Express, mount express.raw({ type: "application/json" }) on the webhook route before any global express.json().

Use the secret from Console → Developers → Webhooks for the same tenant that sent the event. Rotation takes effect immediately, so a rotate that hasn't been deployed to your server yet fails until you push the new secret.

If no signing secret is saved for the tenant, Obsidian sends the delivery with no X-Webhook-Signature header at all. Reject missing-header deliveries the same as mis-signed ones, and configure a secret before production.

Keep the server NTP-synced (the check rejects t more than 5 minutes from now), and compare with hmac.compare_digest / crypto.timingSafeEqual / hmac.Equal — never ==.

402 insufficient_credits won't resolve on retry — it clears only when the balance is topped up. Surface a graceful "verification temporarily unavailable" state to the applicant; don't 500 at them and don't loop retries.

POST /v3/session/ and POST /api/v1/sessions/ return credits_remaining — the cheapest possible balance check since you're already making the call. Alert when it crosses a floor you set, before the first 402.

GET /v3/usage/workflows/ aggregates spend per workflow and GET /v3/credits/ledger/ gives the line-by-line debit history (creating a session debits the SESSION_CREATE rate plus each chargeable module the workflow runs). See Credits.

It's the same tenant key, sent differently: x-api-key: <key> on the ThirdFactor Verify API (/v3), and Authorization: Bearer <key> on the partner API (/api/v1). A 401 on only one surface almost always means a header-name bug, not a bad key — a key that authenticates on one surface authenticates on the other.

A 401 on both surfaces means the key itself is missing, malformed, or was rotated/revoked. Create a new key in Console → Settings → API keys and deploy it. You can run the old and new keys in parallel during cutover.

The key is a secret. If it's in a browser bundle or mobile binary, treat it as leaked and rotate immediately — the SDKs never need it; they only receive the url your backend minted. See Authentication.

Camera access requires a secure origin. The url Obsidian returns is already HTTPS on your flow domain — don't proxy it through an insecure origin or downgrade the scheme.

If you render the hosted flow inside an iframe or a native WebView, the parent must delegate camera (and microphone, for liveness) permission to it — e.g. allow="camera; microphone" on a web iframe, or the platform's WebView permission callback on mobile. Without delegation the inner page can't prompt at all. See SDKs overview.

Once a browser permission is denied for the origin, the flow can't re-prompt programmatically — the user has to re-enable camera access for the site in their browser settings and reload.

NFC needs the device's NFC radio, which a WebView can't reach — so it's iOS, Android, and Flutter only. On web (or a device without an NFC reader), an NFC_VERIFICATION step transparently falls back to server-side manual review (nfc_not_available) instead of blocking the applicant. If you expected an on-device read and got a fallback, check the host actually advertises the nfc capability. See NFC verification.

The BAC key is derived from the MRZ — documentNumber, dateOfBirth, dateOfExpiry (each YYMMDD for the dates) — or a CAN for PACE. A wrong_key error almost always means one of those came from a bad OCR read; re-derive them from the confirm-details prefill or the scanned document and retry.

timeout and tag_lost are handling problems, not software bugs: the chip sits in a specific spot (often the top of a passport's photo page), and phones vary in antenna placement. Tell the user to lay the phone flat and hold still. Retrying is safe.

The hosted URL is time-boxed and single-use. For /v3, lifetime is set by expires_in_hours (1..720, default 48); for /api/v1, by session_ttl_minutes (or the tenant default). Once it lapses the session moves to expired and the URL stops working — there's no resume.

If you email a link now and the applicant clicks it days later, it may be past expires_at. Create the session close to when the applicant will actually use it, or set a lifetime that comfortably covers your delivery + response window.

An expired (or already-completed) session can't be reopened. Create a fresh one — reuse the same vendor_data so it still links back to the same identity/user. For a still-valid /api/v1 application you can extend the current URL with PATCH /api/v1/applications/<id>/ before it lapses, but never after.

The callback_url return is a "you're done" signal for the applicant — it is not an authoritative, signed decision. Never grant access or move value based on the redirect alone. Gate real actions on the HMAC-signed webhook or a server-side GET /v3/session/<id>/decision/ read keyed by vendor_data.

The applicant may land back on your page while the session is still in_progress or in_review. Show a neutral "thanks, we're finishing up" page and resolve the real outcome asynchronously from the webhook — don't try to render approved/declined from the redirect.

callback_url must be an absolute URL you actually serve. Test it by hitting it directly before wiring it into the create call.

Without it, a retried POST /v3/session/ after a timeout creates a second session and debits credits again — the server can't tell it's a retry. With it, a repeat create with the same key returns the original session (201) and is never charged twice.

Generate the key from data that doesn't change across retries — a queue message ID, or a user + intent tuple — not from a per-attempt timestamp. A key that changes on retry gives you no replay protection. On /api/v1/sessions/, the JWT's jti plays the same role; keep it stable per logical session.

If duplicates already exist, join them back to your user via vendor_data / external_user_id (the field designed for correlation) and pick the one the applicant actually completed. See Errors → idempotency.