# Errors and troubleshooting

Canonical page: https://docs.ovok.com/authentication/troubleshooting

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 [#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](/authentication/project-setup#1-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`](/settings-and-features/settings/patient-login-enabled) is `false`. | Set it to `true`. |
| `403` `Login is not enabled for this project.` | Practitioner `login/token` | [`PRACTITIONER_LOGIN_ENABLED`](/settings-and-features/settings/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`](/settings-and-features/settings/patient-registration-enabled) and the AccessPolicy. |
| `403` `Registration is not enabled for this project.` | Practitioner `register` | [`PRACTITIONER_REGISTRATION_ENABLED`](/settings-and-features/settings/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`](/errors/practitioner-registration-not-configured) | Practitioner `register` | Registration is on, but [`DEFAULT_PRACTITIONER_ACCESS_POLICY`](/settings-and-features/settings/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](/authentication#limits-you-will-meet) and [the full rate-limit headers](/slim-apis#errors-on-every-route). |

<Recording name="ovok-console-events-request-log" alt="Searching the Console request log for a failed route and inspecting its status and trace timeline" />

## It runs, but not as I expected [#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](/settings-and-features#defaults-and-dependencies). |
| 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`](/settings-and-features/settings/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`](/settings-and-features/settings/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`](/settings-and-features/settings/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](/email-templates/map-templates) and `ready`). If any is missing, Ovok falls back silently. | Check the [requirements](/authentication/patient-registration#business-email-sign-up). |
| I [`locked`](/errors/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`](/settings-and-features/settings/patient-login-enabled) to `true`. |

## Related [#related]

- [Authentication](/authentication)
- [Set up your project](/authentication/project-setup)
- [Settings and features](/settings-and-features)
