# Domain Error Codes

The API returns errors as `success=false` with `error.code`, `error.message`, optional field errors and optional context.

| Code | Meaning |
|---|---|
| `UNAUTHENTICATED` | Missing, invalid or revoked bearer token. |
| `FORBIDDEN` | Authenticated user is not authorized for the record/action. |
| `INVALID_CREDENTIALS` | Generic login failure. |
| `PATIENT_DUPLICATE_POSSIBLE` | A possible duplicate patient was found. |
| `SLOT_NOT_AVAILABLE` | Appointment slot is unavailable or conflicted. |
| `OUTSIDE_WORKING_HOURS` | Requested time is outside the active practice schedule. |
| `DOCTOR_NOT_ASSIGNED` | Doctor/location practice pair is invalid/inactive. |
| `TOKEN_ALREADY_IN_USE` | Manual token conflicts in the active queue scope/date. |
| `TOKEN_RANGE_EXHAUSTED` | Automatic token range has been exhausted. |
| `INVALID_TOKEN` | Token is outside configured limits. |
| `INVALID_STATUS_TRANSITION` | Requested appointment/queue transition is not allowed. |
| `PAYMENT_EXCEEDS_BALANCE` | Payment or fee change would exceed the allowed balance. |
| `IDEMPOTENCY_KEY_REUSED` | A payment/refund idempotency reference was reused for another object. |
| `CANCELLATION_CUTOFF_PASSED` | Patient cancellation cutoff has passed. |
| `RESCHEDULE_CUTOFF_PASSED` | Patient reschedule cutoff has passed. |
| `ACCOUNT_DISABLED` | User or organization is inactive. |
| `HTTPS_REQUIRED` | Production API request was not received through HTTPS. |
| `REPORT_RANGE_TOO_LARGE` | Report range exceeds the supported maximum. |
| `VALIDATION_FAILED` | Request validation failed; inspect `error.fields`. |
| `STALE_RECORD` | Reserved for clients using optimistic-version conflict handling. |
