Skip to main content

Errors and troubleshooting

All eight tenant authentication routes answer errors in one JSON shape:

Response field	Example	Meaning
`statusCode`	`400`	HTTP status code.
`error`	`Bad Request`	Name associated with the status.
`timestamp`	ISO 8601 timestamp	When the request was handled.
`path`	`/auth/tenant/Patient/login/start`	Route that answered.
`message`	`Username or password is incorrect.`	Error description. For `422`, this is a list of `{ path, message }` entries, one per invalid field.
`requestId`	UUID	Identifies this request; include it when asking for help.

Branch on statusCode first and on message second. Every error is held back to take at least one second, whatever the cause, so a slow failure is not an outage.

Find your message

Status and message	Routes	Likely cause	What to do
`404` `Tenant not found.`	Patient `login/start` and `register`; practitioner `login/token` and `register`	The `tenantCode` is wrong.	Find your tenant code.
`400` `Username or password is incorrect.`	Both `login/start`	A wrong email or password, an account that does not exist, an account without a password, or an account of the other type or another tenant. Deliberately one answer.	Check the audience: patients use the patient routes, practitioners the practitioner routes.
`403` `Login is not enabled.`	Patient `login/start`	`PATIENT_LOGIN_ENABLED` is `false`.	Set it to `true`.
`403` `Login is not enabled for this project.`	Practitioner `login/token`	`PRACTITIONER_LOGIN_ENABLED` is `false` for the chosen project.	Set it to `true`, or let the user choose another tenant.
`403` `Registration is not enabled for this project.`	Patient `register`	The switch is `false`, or the project has no default patient AccessPolicy. The message is the same.	Check `PATIENT_REGISTRATION_ENABLED` and the AccessPolicy.
`403` `Registration is not enabled for this project.`	Practitioner `register`	`PRACTITIONER_REGISTRATION_ENABLED` is not `true`. It is off when unset.	Set it to `true` after setting the default policy.
`409` with `error` `practitioner_registration_not_configured`	Practitioner `register`	Registration is on, but `DEFAULT_PRACTITIONER_ACCESS_POLICY` is missing, unreadable or from another project.	Set a valid policy.
`409`	Practitioner `register`	Another registration for the same email is running.	Retry.
`400` `Registration failed.`	Both `register`	The email already has an account. For patients, in this project; for practitioners, in any project.	Sign in instead, or invite the practitioner.
`400` `Invalid MFA token.`	Patient `login/mfa`	The code is wrong, or the `loginId` is unknown.	Ask for a fresh code.
`400` `Invalid MFA token or user.`	Practitioner `login/mfa`	The same.	Ask for a fresh code.
`400` `Code verification failed.`	Both `login/token`	The `sessionCode` or `codeVerifier` is wrong.	Check that you send the verifier whose hash you sent as `codeChallenge`, and a session code from the same attempt.
`404` `Login not found.`	Practitioner `login/token`	The session code is unknown.	Start sign-in again.
`404` `Account not found.`	Practitioner `login/token`	The practitioner has no membership in the chosen tenant.	Choose a `tenantCode` from the `profiles` list.
`400` `Invalid user profile.`	Both `login/token`	The session belongs to another type of account.	Use the other audience's routes.
`400` `The continue-as-patient link is invalid or has expired.`	Patient `register`	The `continueAsPatientToken` is wrong, expired (7 days), or for another email or project.	Use the link from the invitation email, within 7 days of it being sent.
`422` and a list of fields	Any	A field is missing or invalid: `mfaToken` shorter than 6 characters, `loginId` not a UUID, an empty practitioner `password`, and so on.	Fix the fields named by `path`.
`429`	Any	Too many requests from one IP address.	Wait a minute. See the limits.

It runs, but not as I expected

What you see	Why	Fix
`GET /v1/project/settings` says `false`, but people can sign in or register	An unset Boolean reads as `false` even where the flow is on.	Set the key to the value you intend. See unset settings.
I switched sign-in off and users are still in	Switching off stops new sign-ins, not sessions that already exist. Tokens last up to an hour.	Expect up to an hour; there is no instant cut-off.
A practitioner enters the right password and MFA code and is then refused	`PRACTITIONER_LOGIN_ENABLED` is checked at `login/token`, after the first two steps.	Handle `403` at the last step.
A patient registered even though login is off	Registration returns tokens and does not check the login switch.	Use the registration switch to stop sign-ups.
Patients still appear after I turned registration off	Invitations and first-time Google or Apple sign-in also create patients.	Turn `PATIENT_INVITATION_ENABLED` off too.
A work email registered as a patient, not as a clinician invitation	The invitation needs `CLINICIAN_INVITE_ON_BUSINESS_EMAIL`, a valid default practitioner AccessPolicy, a practitioner app URL, a patient app URL and a working invitation email (`CLINICIAN_SIGNUP_INVITE` mapped and `ready`). If any is missing, Ovok falls back silently.	Check the requirements.
I locked myself out of the dashboard	Project admins are not exempt from the practitioner sign-in switch.	Keep an admin session open while you change it.
A new project refuses patient sign-in	Projects created with `POST /v1/slim/project/child` start with patient sign-in off.	Set `PATIENT_LOGIN_ENABLED` to `true`.

Find your message
It runs, but not as I expected
Related