Errors

Partner-facing codes from /session, /session/{id} and /revoke when isSuccess is false. Read errorCode (and HTTP status ≈ statusCode).

errorCode	HTTP	Typical cause	What to do
`unauthorized`	401	Wrong id/secret or bad Basic header	Fix server credentials
`missing_parameters`	400	Missing `userRef`, `state` or `returnUrl` (or no session id in the path)	Send all required fields
`destination_required`	400	`destination` missing or not a usable phone number	Send the phone number; the hosted UI does not ask for it
`invalid_return_url`	400	`returnUrl` is not registered for this client, or differs from the registered string	Register the exact URL and send it verbatim — see below
`invalid_channel`	400	`channel` is not `"sms"`	Use `"channel": "sms"`
`invalid_operation_sensitivity`	400	`operationSensitivity` is not `"normal"` or `"sensitive"`	Use `"normal"` or `"sensitive"`
`idempotency_key_too_long`	400	`Idempotency-Key` over 255 characters	Use a shorter key
`idempotency_key_reused`	422	Same `Idempotency-Key`, different payload	New attempt → new key
`idempotency_request_in_flight`	409	Same key while the original request is still running	Wait a moment and retry with the same key

`invalid_return_url` — the exact-match rule

The registered URLs are compared to your returnUrl as whole strings, case-sensitively. It is not a prefix match and not a host match, so every one of these fails:

You registered	You sent	Result
`https://app.com/verify/done`	`https://app.com/verify/done/`	`invalid_return_url` (trailing slash)
`https://app.com/verify/done`	`https://app.com/verify/done?x=1`	`invalid_return_url` (query string)
`https://app.com/verify/done`	`http://app.com/verify/done`	`invalid_return_url` (scheme)
`https://app.com/verify/done`	`https://www.app.com/verify/done`	`invalid_return_url` (host)
`http://localhost:5173/verify/done`	`http://localhost:4200/verify/done`	`invalid_return_url` (port)

The failure happens on POST /session, before the user goes anywhere — so it appears in your server logs, never in front of the user.

Hosted verify page (`400`)

The verify endpoint is opened by POSTing the handoff token to it:

Symptom	Cause	Fix
`400` on `GET {verifyUrl}?…`	Any query string on the verify endpoint. No flow value may travel in a URL on that path	POST `hx` as a form field instead — see Frontend overview
`400` on `POST {verifyUrl}`	`handoff` already redeemed (replay), or expired past its 120 s TTL	`handoff` is single use. Create a new session and hand off again; do not create the session minutes before the user is ready
`400` on `POST {verifyUrl}`	`hx` missing, or the body is not a form content type	Submit a real form with a hidden `hx` field
Blank frame instead of the verify page	You tried to iframe it	The page sends `frame-ancestors 'none'`. Open it top-level with the form POST

HTTP 401 with empty body

Basic header missing or not parseable. Send:

Authorization: Basic base64("clientId:secret")

Landing page and result

Nothing is delivered to your server, so every failure here is a read that did not happen or a check that did not pass.

Symptom	Cause	Fix
Landing page shows “pending” though the user verified	You never called `GET /session/{sessionId}`, or you called it with an id that is not yours	Read the status from the landing route with Basic auth, using the `sessionId` from your own pending record
`status: "pending"` for an id you believe exists	`pending` also covers “unknown id” and “belongs to another client” — there is no `404`	Trust your own record for existence; check you are using the right `client_id`
The action ran for the wrong user	You acted on the status without comparing `userRef` to your record	Require `state` and `userRef` to match before fulfilling
The action ran even though the user never verified	You treated arrival on the landing URL as success. A failed verification returns the browser with the same `?session_id=&state=` a successful one does	Gate fulfilment on `status == "verified"` from `GET /session/{id}`, never on arrival
`status: "failed"` and you want to know why	`reason` says which terminal condition ended it: `otp_locked`, `device_changed`, `session_binding_failed`	Show it to the user and let them start a new session. Branch on `status`; treat an unknown `reason` as generic failure
The action ran twice	The landing page was reloaded, or your sweep also fired	Make `onVerified(sessionId)` idempotent: perform and mark used in one transaction
Landing page arrived without `session_id`/`state`	The return always carries them, so something between Authentica and your app rewrote the URL (a redirect that dropped the query string, a router that stripped it)	Register the exact landing URL, and read `session_id`/`state` before any client-side routing runs
Your landing route is an open redirect	You stored a URL in `state` and redirected to it	Never do that. Keep destinations server-side — see Routing many actions

Frontend

Symptom	Fix
`no_verify_url`	Your start route must return both `verifyUrl` and `handoff`
Nothing happens on `window.location.href = verifyUrl`	Navigation is not supported. Auto-submit a form POSTing `hx` to `verifyUrl`
CORS errors calling Authentica from the browser	Call your API instead; do not call `/session` from JS with the secret

Get started

Backend

Frontend

Reference

`invalid_return_url` — the exact-match rule

Hosted verify page (`400`)

HTTP 401 with empty body

Landing page and result

Frontend

​invalid_return_url — the exact-match rule

​Hosted verify page (400)

​HTTP 401 with empty body

​Landing page and result

​Frontend

`invalid_return_url` — the exact-match rule

Hosted verify page (`400`)

HTTP 401 with empty body

Landing page and result

Frontend