Errors and troubleshooting
The error format of the tenant authentication routes, every message you can meet, and what to check and change when sign-in or registration does not behave as expected.
All eight tenant authentication routes answer errors in one JSON shape:
| Response field | Example | Meaning |
|---|---|---|
statusCode | 401 | HTTP status code. |
error | Unauthorized | Name associated with the status. |
timestamp | ISO 8601 timestamp | When the request was handled. |
path | /v1/auth/tenant/Patient/login/start | Route that answered. |
message | Invalid email or password. | 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. |
401 Invalid email or password. | 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 | Both login/start | 5 failed sign-ins for this email within 15 minutes. The account is locked for 15 minutes, whatever the IP address. | Wait the seconds in the body's retryAfterSec, then sign in with the right password. |
429 | Any | Too many requests from one IP address. The response has Retry-After in seconds and the body has the same value in retryAfterSec. | Wait that many seconds. See the limits and the full rate-limit headers. |
- 1Search the request log for a route to find its failed request.
- 2Open it to inspect the status and request timeline.
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. |
Related
Last updated on
Accept or withdraw the terms
Accept or withdraw the terms for the signed-in practitioner with POST /v1/me/consent/legal and get the resulting legal consent back.
Overview
Learn how Ovok AccessPolicies shape project membership access, how default policies are assigned, and how Signals routes use custom policy rows.