Errors

Every error is JSON with the same three parts: a human-readable message, a stable machine-readable code, and — for input problems — errors keyed by attribute:

{
  "message": "Validation failed.",
  "code": "validation_failed",
  "errors": {
    "starts_at": ["The starts at field must match the format YYYY-MM-DDTHH:MM:SS."],
    "patient_id": ["Patient not found or deleted."]
  }
}

{ "message": "This group appointment is full.", "code": "group_full" }

Status	When	What to do
`401`	No key, or an invalid, revoked or wrong-account key	Check the `Authorization: Bearer …` header; create a new key under Developers → API Keys
`403`	The API key is read-only and the request writes; or a connector’s team member is not permitted (connector disabled for the role, or the role lacks the permission for this action)	Use a read & write key, or ask an account owner to adjust the role under Settings → Security → Roles
`404`	No such resource, or no record with that id on this account; or the PracticeHub API is not available on this account	Nothing to retry — the record is gone, never existed here, or the account isn’t on the new platform yet
`405`	The resource does not support that operation (for example creating a `line_items` row)	See `write_operations` in `GET /schema/{resource}`
`409`	A business rule refused the change — appointment already processed, group full, invoice already paid; or an `Idempotency-Key` still in flight	Show `message` to the user; the request will not succeed until the state changes (for idempotency, wait and retry)
`422`	Invalid input — unknown attribute, wrong type or format, missing required field, or a referenced record that does not exist	Read `errors`; fix and resend
`429`	Rate limit exceeded (120 requests per minute per account)	Wait for the next minute and retry with backoff
`500`	Something went wrong on our side	Retry with backoff; contact support quoting the `X-Request-Id`

Error code catalogue

Branch on the status code, the code, and the attribute keys in errors. message text is written for humans and may change; do not parse it. Codes are stable within the current version — new ones may be added, existing ones are not renamed. Every code below is emitted by name by the API — none are aspirational.

401 — Unauthorized

Code	When	What to do
`unauthenticated`	No key, or the key is invalid, expired or revoked	Check the `Authorization: Bearer …` header; create a new key
`user_inactive`	A connector’s team member (the person behind an OAuth connection) has been deactivated in PracticeHub	Reconnect with an active team member, or have an owner reactivate the account

403 — Forbidden

Code	When	What to do
`key_read_only`	The API key is read-only and the request writes	Use a read & write key
`connector_not_permitted`	The connector’s team member no longer has Connect AI apps on their role	Restore the permission, or reconnect as a user who has it
`permission_denied`	The connector’s team member’s PracticeHub role does not allow this read, write or delete (`message` names the missing permission), or the record is outside their own-patients / own-calendar scope	Adjust the role under Settings → Security → Roles, or act on a record within scope
`account_disabled`	The PracticeHub account this key belongs to has been disabled	Nothing to retry — the account owner needs to talk to PracticeHub
`account_inactive`	The account’s subscription has lapsed; the web app is limited to billing until it is settled	Nothing to retry until the account is active again
`forbidden`	Generic fallback for a credential refusal not covered by a more specific code above (reserved for future use)	Treat as a permissions problem; contact support if the cause isn’t obvious

404 — Not Found

Code	When	What to do
`not_available`	The PracticeHub API is not enabled on this account (not yet native to PracticeHub 2.0)	Nothing to retry — talk to your PracticeHub contact about migrating
`not_found`	No such resource, or no record with that id on this account (also returned by `GET /schema/{resource}` for an unknown resource)	Nothing to retry — the record is gone, never existed, or belongs to another account

405 — Method Not Allowed

Code	When	What to do
`unsupported_operation`	The resource does not expose that operation — a read-only resource, or an operation like `PUT` or deleting a `payment_methods` row	Check `write_operations` in `GET /schema/{resource}`
`method_not_allowed`	The HTTP method isn’t valid for that URL at all	Use the documented method for the route

409 — Conflict

Code	When	What to do
`idempotency_key_in_flight`	The same `Idempotency-Key` is already being processed by another request	Wait briefly and retry with the same key
`appointment_rule`	The scheduling service refused a state change — already processed, cannot un-arrive, cannot delete a processed/cancelled/missed visit, and similar	Show `message`; the appointment’s state has to change first (unprocess, reinstate, void its invoice)
`group_full`	`POST /appointments` with `group_master_id`: the group session has no places left	Pick a different session, or wait for a cancellation
`billing_rule`	The billing service refused — over-allocating a payment or invoice, editing a void or care-plan invoice, and similar	Show `message`; re-read the invoice/payment/allocation state before retrying
`refund_exceeds_net`	`POST /refunds`: the amount is more than is left of the payment after earlier refunds	Read the payment’s refunds (`GET /refunds?payment_id=eq:…`) and refund at most the remainder
`release_pair`	`POST /refunds`: the payment is one leg of a credit transfer	Reverse the transfer in PracticeHub instead
`refund_locked`	`PATCH` / `DELETE /payments/{id}` on a refund row	A refund is never edited or voided; reverse it in PracticeHub
`tag_locked`	`DELETE /patient_tags/{id}` on a tag a care plan put on the file	The plan takes it off when it ends; leave it
`file_store_failed`	The uploaded file could not be written to storage	Retry the upload; if it keeps failing, contact support with the `X-Request-Id`
`file_delete_failed`	The file record could not be deleted	Retry; if it keeps failing, contact support
`conflict`	Generic fallback for a state conflict not covered by a more specific code above (reserved for future use)	Re-read the record’s current state before retrying

422 — Unprocessable Entity

Validation

Code	When	What to do
`validation_failed`	Input failed schema-level validation — unknown attribute, wrong type/format, missing required field, unsortable/unfilterable attribute in a query string, a reused `Idempotency-Key` with a mismatched fingerprint, a cursor issued for a different query	Read `errors`; fix and resend
`invalid_input`	A domain check rejected the input in a way not covered by a more specific code (for example `GET /availability` query validation)	Read `message`/`errors`; fix and resend

Referenced record not found — errors names the attribute; the reference is missing, deleted, or not on this account

Code	Attribute	Where it’s raised
`patient_not_found`	`patient_id`	Appointments, patients (referral), payments, invoices, patient logs, files
`location_not_found`	`location_id` / `default_location_id`	Appointments, `GET /availability`, patients
`practitioner_not_found`	`practitioner_id`	Appointments, `GET /availability`
`appointment_type_not_found`	`appointment_type_id`	Appointments, `GET /availability`
`appointment_not_found`	`rescheduled_appointment_id`	`GET /availability` (rescheduling)
`group_not_found`	`group_master_id`	`POST /appointments` (joining a group session)
`referral_source_not_found`	`referral_source_id`	Patients
`patient_log_not_found`	`patient_log_id`	Patient log tags
`phone_number_not_found`	`numbers.{i}.id`	Patients (an `id` in `numbers[]` that isn’t one of the patient’s)
`form_not_found`	`form_id`	Clinical notes — no such template, or it isn’t `active`

Clinical notes

Code	Attribute	When
`appointment_patient_mismatch`	`appointment_id`	The linked appointment belongs to a different patient than `patient_id`
`form_type_invalid`	`form_id`	The template exists and is active, but isn’t a `practitioner` or `scribe` form — a `patient`-type template, for example
`unknown_field`	`data`	A key in `data` isn’t a field name (or id) on the template’s schema — refused rather than silently dropped

Appointments & booking

Code	When	What to do
`patient_required`	`POST /appointments`: no `patient_id`, and the type isn’t a group session master	Send `patient_id`
`resource_unavailable`	`resource_id` missing/inactive/not at that location, or missing on a resource-view location (`calendar_view` = `1`)	Choose an active resource from `GET /resources?location_id=…`
`end_before_start`	A `PATCH` would leave the appointment ending at or before its start — sending `ends_at` or `starts_at` alone is checked against the time the appointment keeps	Send both times, or an `ends_at` after the start
`note_too_long`	`note` over 1000 characters	Shorten it
`cancel_note_too_long`	`cancel_note` over 1000 characters	Shorten it
`not_online_bookable`	`GET /availability?visibility=online`: the location, type or practitioner isn’t enabled for online booking	Use `visibility=all` for the staff view, or enable online booking for that combination
`availability_not_configured`	`GET /availability`: no rota or service configured for that location + appointment type	Configure availability in PracticeHub, or query a different combination

Patients & referrals

Code	Attribute	When
`referral_self`	`referral_source_id`	A patient was named as their own referral source
`referral_patient_required`	`referral_source_id`	`referral_source_type` is `patient` with no `referral_source_id` — an unmatched-referrer name (the state a public form can leave) isn’t something the API, with admin-level access, is allowed to create
`phone_type_required`	`numbers`	A phone number in `numbers[]` was sent without `type`

Payments & billing

Code	Attribute	When
`payment_method_not_found`	`payment_method_id`	Not a payment method of this account
`payment_method_inactive`	`payment_method_id`	The method exists but is switched off
`card_payment_not_allowed`	`payment_method_id`	A method a payment provider collects (card, Direct Debit, a custom gateway) — no money is collected through this endpoint
`payment_method_not_recordable`	`payment_method_id`	Any of PracticeHub’s special types (negative ids: refund, credit, write-off, transfers, rewards, card on file, direct debit) — PracticeHub writes these itself; they can’t be recorded directly
`provider_refund_not_supported`	`payment_id`	`POST /refunds` on a payment a provider collected (card, Direct Debit) — refund it through the provider in PracticeHub
`amount_out_of_range`	`amount` / `price`	Outside the range the ledger stores (±99,999,999.99, two decimal places)
`quantity_out_of_range`	`quantity`	Outside the range a line item’s `quantity` stores
`billable_item_not_found`	`billable_item_id`	Unknown service or product on a line item

Files

Code	When	What to do
`file_type_not_allowed`	Extension not in the allowed set, or not an image for a `patient_profile` upload	Use an allowed extension — jpg/jpeg/png/mp3/pdf/txt/csv/doc/docx/xls/xlsx (image-only for profile photos)
`tag_not_found`	`POST /patient_tags` with a `tag_id` that is not an active tag of the account	Pick one from `GET /tags`
`patient_log_mismatch`	`patient_log_id` doesn’t belong to the patient on the upload	Use one of the patient’s own log entries
`profile_photo_not_image`	Trying to set a non-image file as `patient_profile`	Only PNG/GIF/JPG can be a profile photo
`log_entry_locked`	`PATCH` / `DELETE /patient_logs/{id}` on an entry the API did not create	Only entries created through the API (`source: api`) can be changed or deleted through it — the rest are PracticeHub’s audit trail
`patient_log_attachment_locked`	Trying to retype a file attached to a patient log	A `patient_log` attachment keeps its type — remove and re-upload instead

Idempotency

Code	When	What to do
`idempotency_key_invalid`	`Idempotency-Key` is over 255 characters	Use a shorter key
`idempotency_key_reused`	The same key was sent with a different request body	Use a new key per distinct operation

413 — Payload Too Large

Code	When	What to do
`payload_too_large`	The request body is over the server’s size limit — in practice a `POST /files` upload	Send a smaller file

429 — Too Many Requests

Code	When	What to do
`rate_limited`	Rate limit exceeded (120 requests/minute/account)	Wait for `Retry-After` / the next window, then retry with backoff

500 — Internal Server Error

Code	When	What to do
`server_error`	Something went wrong on our side — the response never leaks SQL or stack detail, even with debug on	Retry with backoff; contact support quoting the `X-Request-Id`

503 — Service Unavailable

Code	When	What to do
`service_unavailable`	PracticeHub is briefly in maintenance (a deploy)	Wait for `Retry-After` seconds, then retry — nothing was processed

Every other HTTP status the platform can produce uses the same {message, code} envelope: a 403 from a permission gate is permission_denied, 413 is payload_too_large, 503 is service_unavailable, and code is http_error only when no more specific code applies.

Handling errors well

Retry taxonomy — branch on status, not on whether the call “felt” transient:

Status	Retry?	How
`429`, `5xx`	Yes	Exponential backoff with jitter. On a `POST`, reuse the same `Idempotency-Key` so a retried write can’t create the record twice.
`409` (except `idempotency_key_in_flight`)	Only after the state changes	`message` names the conflict — the appointment has to be unprocessed, the invoice un-voided, etc. Retrying unchanged input just fails again.
`409 idempotency_key_in_flight`	Yes, briefly	The first request is still running — wait a second and retry the same key.
`422`	No, until the input changes	Fix the field(s) in `errors` first.
`401`, `403`	No	The credential or role has to change — a retry loop just burns rate limit.

Log the code, not the message. message is written for a human and may be reworded without notice; code is the stable contract your branching logic and your alerts should key off. Store X-Request-Id alongside it — it’s what support needs to pull the exact request from Developers → API Logs.
Don’t parse message to detect a specific failure — the errors object (for 422) and code (for everything) already tell you exactly what happened, in a shape that won’t drift under you.
Idempotency keys make retries safe, not fast — see Idempotency keys for the full replay behaviour (24-hour window, same-key-same-body semantics).

Diagnosing

Every response includes an X-Request-Id. The same id appears against the request on the account’s Developers → API Logs page — status, latency and the caller — and support can trace it from there.

Rate limits

X-RateLimit-Limit and X-RateLimit-Remaining are on every response. The limit is per account: every API key on the account shares one REST budget (120 requests a minute), so a burst from one integration spends the same budget as every other. AI connectors have a separate budget of their own and never eat into it.

Getting started

Concepts

Working with the API

Ship it

Resource guides

Importing your data

Error code catalogue

401 — Unauthorized

403 — Forbidden

404 — Not Found

405 — Method Not Allowed

409 — Conflict

422 — Unprocessable Entity

413 — Payload Too Large

429 — Too Many Requests

500 — Internal Server Error

503 — Service Unavailable

Handling errors well

Diagnosing

Rate limits

​Error code catalogue

​401 — Unauthorized

​403 — Forbidden

​404 — Not Found

​405 — Method Not Allowed

​409 — Conflict

​422 — Unprocessable Entity

​413 — Payload Too Large

​429 — Too Many Requests

​500 — Internal Server Error

​503 — Service Unavailable

​Handling errors well

​Diagnosing

​Rate limits

Error code catalogue

401 — Unauthorized

403 — Forbidden

404 — Not Found

405 — Method Not Allowed

409 — Conflict

422 — Unprocessable Entity

413 — Payload Too Large

429 — Too Many Requests

500 — Internal Server Error

503 — Service Unavailable

Handling errors well

Diagnosing

Rate limits