invalid_key | 401 | The key is missing, malformed, unknown, revoked, expired, or the secret is wrong. One code for all of these — see Authentication. |
not_found | 404 | The record doesn’t exist, or it exists but this key can’t reach it (wrong clinic, for example). These two situations return the identical response on purpose — the difference would tell you something exists that you can’t see. |
scope_missing | 403 | The key doesn’t carry the scope this endpoint needs. See Permissions. |
plan_required | 403 | The clinic’s current plan doesn’t include this resource at all, regardless of what your key was granted. |
ip_not_allowed | 403 | The request came from an address this key’s allow-list doesn’t cover. Names nothing about which addresses ARE allowed. |
invalid_request | 400 | The request body or query string failed validation. This includes a medicine or diagnosis code that is not recognised (an RxNorm or ICD-10 code we do not hold), which is refused rather than saved. See Medications and Conditions. It also covers a change to a referral the clinic has already acted on: see Referrals. |
rate_limited | 429 | You’ve exceeded the request limit for this key. See Rate limits. |
sandbox_only | 403 | A test key asked for a real clinic_id. A test key may reach only its own workspace’s sandbox — see Authentication. |
not_verified | 403 | A live organization key asked for a clinic while its workspace’s verification isn’t current. |
workspace_plan_required | 403 | A live organization key’s workspace is on the Sandbox plan. See Plans and pricing. |
quota_exceeded | 429 | A contracted Enterprise workspace has used its included requests for the month under a hard cap. Essential is billed for overage instead — see Usage and billing. |
limit_reached | 403 | A contracted Enterprise workspace has reached a hard-capped limit (for example, connected clinics). |
not_available | 403 | A request for a patient-data scope arrived while patient data is not open on the platform. |
approval_required | 403 | An organization’s key, or a connection request, asked for a patient-data scope, but the organization has no current approval for patient data. Apply on Settings → Verification; a revoked approval returns this on the next request. |
kind_not_approved | 403 | The organization is approved for patient data, but not for the kind this scope belongs to (on a key or on a connection request). |
terms_required | 403 | The workspace has not accepted the current API Terms of Use. Creating a live key is refused at once; a live key’s requests are refused once the notice period after the terms were published has ended. An owner or administrator accepts on Settings → Agreements. Test keys are never affected. |
client_reference_conflict | 409 | You sent a client_reference you have already used for a different item. Use a new reference, or resend the original item. See Conditions. |
submission_not_pending | 409 | You tried to change an item that a clinician has already decided, or that was withdrawn. Send a new item instead. See Reviewing outside submissions. |
coverage_exists | 409 | The patient already has a coverage with that payer. The error carries the existing coverage’s id when you may see that patient; change it with PATCH instead. See Insurance. |
payer_not_enabled | 409 | The payer_id is not one of the payers the clinic has enabled. Ask the clinic to enable it under Settings → Insurance. See Insurance. |
activation_requires_staff | 409 | You asked for a coverage to be active. Only the clinic’s staff can activate one, by confirming it. See Insurance. |
care_provider_clinic_managed | 409 | You tried to change or remove an outside care provider your app did not add. Only the clinic can change it. The contact stays readable, and its editable field is false. See Outside care providers. |
insurance_region_unsupported | 409 | The clinic uses the US insurance setup, which the HMO insurance routes never serve. See Insurance for HMOs and insurers. |
hmo_not_linked | 403 | The action belongs to an insurer (read its claims, vet them, decide authorizations, report a payment) and the clinic has not linked your organization to an insurer. The clinic does this under Settings → API access → Insurer links. See Insurance for HMOs and insurers. |
note_not_editable | 409 | You tried to change a visit (or a note) that your app can no longer change: a clinician has edited the draft since your app opened it, or has signed or finalised it. Read it again to see what the clinic recorded. See Encounters. |
agreement_required | 403 | The data-protection addendum (for an organization’s key) or the API data agreement (for a clinic’s own key) has not been accepted in its current version. |
addon_required | 403 | A clinic’s own key asked for patient data, but the clinic has not added the API add-on. The clinic adds it under Settings → API access. See Getting access to patient data. |
legal_basis_required | 403 | The clinic’s connection to your organization has no recorded legal basis for sharing patient data, so patient data cannot flow on it yet. See Connections. |
patient_cap_reached | 403 | The clinic’s plan has reached its limit of patients, so a new patient cannot be created. |
notification_settings_not_writable | 403 | You tried to change a patient’s own notification consent, which an API key can never change. See Patients. |
controlled_drug_not_api_movable | 403 | A controlled drug cannot be moved through the API, because the movement needs a witness. Staff record it in ClinikEHR. See Inventory. |
unknown_field | 400 | The body named a field the schema (or, for a note, the template) does not have. The answer names the unknown fields and, for a note, the valid ones. See Notes. |
template_not_found | 400 | The note_type or custom_template_id is not a template this clinic has. See Notes. |
too_many_rows | 400 | An import held more than 100 rows. Split it and import it in parts. See Patients. |
limit_exceeded | 400 | A stock change is larger than the limit the clinic has set for one change. See Inventory. |
invalid_gtin | 400 | An identifier with system gtin (or an item’s upc) is not a valid GTIN: it must be digits only, 8, 12, 13 or 14 long, with a correct GS1 check digit. detail and errors[] name the field and the value. Nothing was saved. On an item update only a changed upc is checked; sending back the stored value is accepted. In a partner-code upload only the offending row is refused, with "state": "error". See Inventory and Uploading partner codes. |
signature_required | 400 | The clinic requires a signature to record a pickup (its Require a signature at pickup setting is on) and the collection request carried no signature_data. Send the signature image. See Prescription pickups. |
expiry_required | 400 | Received stock needs an expiry date. See Inventory. |
expiry_mismatch | 400 | That lot already exists with a different expiry date, which a top-up cannot change. See Inventory. |
hazard_location_required | 400 | This item can only be moved to a location rated for it. See Inventory. |
idempotency_key_conflict | 409 | You reused an Idempotency-Key for a different request. Use a new key for a new request. See Retries and idempotency. |
idempotency_key_reused | 409 | A request with this Idempotency-Key is still being processed. Wait, then retry with the same key to get its answer. See Retries and idempotency. |
slot_taken | 409 | The clinician already has an appointment that overlaps this time. Pick another slot. See Appointments. |
no_provider_available | 409 | No clinician who offers this service is free at that time. See Appointments. |
out_of_office | 409 | The clinician’s calendar is blocked at that time. See Appointments. |
invalid_status_transition | 409 | The record cannot move to that status from the one it is in now. |
item_has_stock | 409 | An item that still has stock cannot be archived. See Inventory. |
item_has_history | 409 | An item that has been used cannot be deleted. Archive it instead. See Inventory. |
reason_required | 400 | A lot write-off needs a reason, and the one sent was blank. See Inventory. |
insufficient_stock | 409 | There is not enough usable stock for this movement. See Inventory. |
expired_stock_not_transferable | 409 | Only usable stock can be transferred; the expired part must be written off by the clinic instead. See Inventory. |
batch_rejected | 409 | An external stock batch was rejected and nothing from it was saved. detail names the reason: invalid_rows (a row had no identifier, no stock figure, or a value we could not read), suspicious_shrink or empty. See Inventory. |
external_stock_mode_required | 409 | A stock report was sent to a pharmacy that is not set to take one from another system. The owner switches it on in Settings. Nothing was saved. See Send a stock report. |
already_imported | 409 | A file with exactly this content was already imported for this clinic. See Patients. |
file_expired | 410 | The uploaded import file is no longer held. Upload it again to start a new import. See Patients. |
payload_too_large | 413 | The import body is larger than 10 MiB. See Patients. |