{ "version": "2026-08-14.1", "convention": "UPPER_SNAKE_CASE", "codes": [ { "code": "UNAUTHENTICATED", "http": 401, "stop": "authenticate", "fix_stage": "authentication", "meaning": "No token, an expired token, or a token the rail does not recognise.", "fix": "Refresh proactively on a timer rather than reactively on a 401." }, { "code": "FACILITY_CONTEXT_MISSING", "http": 400, "stop": "authenticate", "fix_stage": "authentication", "meaning": "The facility headers were absent, so no facility-scoped rule could be resolved.", "fix": "Set the facility headers in the HTTP client, not at individual call sites." }, { "code": "OUTSIDE_FACILITY_GEOFENCE", "http": 403, "stop": "any", "fix_stage": "authentication", "meaning": "The call originated outside the configured radius of the facility. Checked before any stop-specific gate.", "fix": "Read distance_m, allowed_radius_m and facility_code from the detail block. Test environments often use a different radius." }, { "code": "MEMBER_NOT_FOUND", "http": 404, "stop": "identify", "fix_stage": "identity", "meaning": "The identifier does not resolve to any registry record.", "fix": "Confirm the identifier TYPE as well as the value. A missing or wrong type is the commonest cause of a false not-found." }, { "code": "IDENTIFIER_CONFLICT", "http": 409, "stop": "identify", "fix_stage": "identity", "meaning": "The identifier matches more than one record and cannot be disambiguated automatically.", "fix": "Collect a second identifier from the person at the desk. Do not retry the same call." }, { "code": "IDENTIFIER_TYPE_REQUIRED", "http": 400, "stop": "identify", "fix_stage": "identity", "meaning": "An identifier value arrived without its type. A number on its own resolves to nothing.", "fix": "Send the pair. A single free-text box is the commonest cause of a \"patient not found\" for a patient who is in the registry." }, { "code": "IDENTIFIER_TYPE_UNKNOWN", "http": 400, "stop": "identify", "fix_stage": "identity", "meaning": "The identifier type is not in the current value set — usually a hard-coded list that has since moved, or a legacy numeric requestIdType sent in place of the string code.", "fix": "Populate the type picker from GET /api/v2/clinical/concepts?system=IDENTIFIER-TYPES and send the string code." }, { "code": "REGULATOR_REQUIRED", "http": 400, "stop": "identify", "fix_stage": "identity", "meaning": "A practitioner was searched by registration number with no regulator. The same digits can be valid under more than one council.", "fix": "Send the regulator alongside the number — KMPDC, COC or NCK. Only a PUID lookup may omit it." }, { "code": "PRACTITIONER_NOT_FOUND", "http": 404, "stop": "identify", "fix_stage": "identity", "meaning": "No practitioner matches that regulator and registration number.", "fix": "Re-check the regulator before re-typing the number; the wrong council is the likelier error." }, { "code": "MEMBER_DECEASED", "http": 409, "stop": "identify", "fix_stage": "identity", "meaning": "The record resolved, but the registry reports the person as deceased (is_alive: false).", "fix": "Stop and escalate clinically. Do not open an encounter or bill against the record." }, { "code": "REGISTRY_TIMEOUT", "http": 504, "stop": "identify", "fix_stage": "identity", "meaning": "The client registry did not answer inside the rail's budget. The lookup may still complete.", "fix": "Retry once with the same lookup_ref so the attempt is de-duplicated rather than recording a second consent. Past your own wait budget, offer a pending state instead of holding the screen." }, { "code": "COVER_INVALID", "http": 404, "stop": "entitle", "fix_stage": "cover", "meaning": "The cover does not resolve, or its status is not active.", "fix": "Re-list covers and let the operator choose again." }, { "code": "COVER_EXPIRED", "http": 409, "stop": "entitle", "fix_stage": "cover", "meaning": "The cover's policy window does not include today.", "fix": "Select a different cover, or collect payment another way." }, { "code": "SCHEME_CODE_REQUIRED", "http": 400, "stop": "entitle", "fix_stage": "cover", "meaning": "The cover is live on more than one scheme and no scheme was named in the selection.", "fix": "Render schemes as covers so the operator makes one selection rather than two." }, { "code": "ELIGIBILITY_REF_NOT_FOUND", "http": 404, "stop": "entitle", "fix_stage": "eligibility", "meaning": "The eligibility reference is unknown or has expired.", "fix": "Re-run eligibility. The reference is visit-scoped and short-lived by design." }, { "code": "PAYER_UNREACHABLE", "http": 502, "stop": "entitle", "fix_stage": "eligibility", "meaning": "The payer did not respond within the configured timeout.", "fix": "Retry — it is safe and idempotent on the selection reference. Do not surface this to the front desk as a patient problem." }, { "code": "CONSENT_REQUIRED", "http": 403, "stop": "consent", "fix_stage": "consent", "meaning": "An operation that reads or acts on a member's record was attempted without a recorded consent.", "fix": "Open a consent session at stop 03 and carry the authorization_ref. Resolving an identity does not need consent; reading a record does." }, { "code": "CALLBACK_URL_REQUIRED", "http": 400, "stop": "consent", "fix_stage": "consent", "meaning": "A consent session was opened with nowhere to deliver its outcome.", "fix": "Send callback_url on the open call. If your system cannot receive inbound calls, send delivery: \"poll_only\" and poll the endpoint the response gives you." }, { "code": "METHODS_NOT_CLIENT_DECLARED", "http": 400, "stop": "consent", "fix_stage": "consent", "meaning": "The open call tried to specify which consent factors to use.", "fix": "Remove the field. Which factors are legal is resolved from the member, facility, payer and benefit — it is never a client choice." }, { "code": "CONSENT_PURPOSE_INVALID", "http": 400, "stop": "consent", "fix_stage": "consent", "meaning": "purpose is not one of the published values.", "fix": "Use visit_open, visit_close, share_record or pii_access. Opening and closing a visit are separate purposes, not one reused." }, { "code": "EMBED_ORIGIN_NOT_REGISTERED", "http": 403, "stop": "consent", "fix_stage": "consent", "meaning": "The page attempting to frame the consent UI is served from an origin the rail does not know.", "fix": "Register every origin that will embed the UI, including staging hosts. The browser will report this as a frame-ancestors refusal with no request reaching you." }, { "code": "SUBJECT_NOT_CONSENTABLE", "http": 403, "stop": "consent", "fix_stage": "consent", "meaning": "No consent can be taken for this person — most often a deceased record.", "fix": "This is a data condition, not a transient failure. Do not retry; resolve the record." }, { "code": "NO_FACTOR_AVAILABLE", "http": 422, "stop": "consent", "fix_stage": "consent", "meaning": "Nothing can legally prove consent for this member, at this facility, right now.", "fix": "The response names the remedy — a whitelist request, adding a verified number, or enrolling prints. Show it. This is never a dead end you should surface as a generic error." }, { "code": "CONSENT_SESSION_PENDING", "http": 409, "stop": "consent", "fix_stage": "consent", "meaning": "An earlier consent session is still open, which blocks creating a new one.", "fix": "Reject the stale session explicitly, then create a new one. Retrying create will keep failing." }, { "code": "CONSENT_SESSION_EXPIRED", "http": 410, "stop": "consent", "fix_stage": "consent", "meaning": "The session outlived its window before it was completed.", "fix": "Open a new session. Expiry is a normal path — a front desk gets interrupted." }, { "code": "CHALLENGE_REJECTED", "http": 422, "stop": "consent", "fix_stage": "consent", "meaning": "A wrong or expired code, or attempts exhausted.", "fix": "Attempts are limited per authorisation; beyond that, a new authorisation object is required." }, { "code": "PAYER_METHOD_BLOCKED", "http": 403, "stop": "consent", "fix_stage": "consent", "meaning": "The requested factor is disabled for this payer and was never offered.", "fix": "Only offer factors the rail returned. Do not render a factor menu of your own." }, { "code": "HARDWARE_MISMATCH", "http": 422, "stop": "consent", "fix_stage": "consent", "meaning": "The capture device does not match this workstation's registration.", "fix": "Register the device against the workstation before capture." }, { "code": "NO_LOCATION_ASSIGNED", "http": 409, "stop": "visit", "fix_stage": "visit", "meaning": "A visit was opened before a service location was set.", "fix": "Set the service location at the front desk. It is a workflow step, not a field you can invent." }, { "code": "BENEFIT_EXHAUSTED", "http": 409, "stop": "visit", "fix_stage": "benefit", "meaning": "The item's balance or counters were consumed — possibly elsewhere, between eligibility and now.", "fix": "Re-check items and offer the operator an alternative. Balances are live and shared across facilities." }, { "code": "WAITING_PERIOD", "http": 409, "stop": "visit", "fix_stage": "benefit", "meaning": "The benefit's waiting window has not yet elapsed.", "fix": "Retry after the date given. Nothing can be done before it." }, { "code": "VISIT_ALREADY_OPEN", "http": 409, "stop": "visit", "fix_stage": "visit", "meaning": "Another active visit of the same class exists for this member.", "fix": "Close the earlier visit first. Concurrent visits of one class are not permitted." }, { "code": "DIAGNOSIS_REQUIRED", "http": 422, "stop": "treat", "fix_stage": "clinical", "meaning": "The visit has no recorded diagnosis, and something downstream — a preauthorisation, a claim — needs one.", "fix": "Record it while the clinician is still in the encounter. A diagnosis reconstructed at submission is a guess with a code on it." }, { "code": "DIAGNOSIS_CODE_INVALID", "http": 400, "stop": "treat", "fix_stage": "clinical", "meaning": "The code is not in the ICD-11 release the payer is validating against, or it is not a codable entity — a chapter or grouping rather than a diagnosis.", "fix": "Populate the picker from the terminology service and send only entries flagged codable. This is the commonest cause of a claim rejected days after the visit." }, { "code": "DIAGNOSIS_NOT_LINKED", "http": 422, "stop": "treat", "fix_stage": "clinical", "meaning": "A diagnosis was recorded without the intervention it justifies, or a billed intervention has no diagnosis behind it.", "fix": "Every diagnosis carries an intervention_code. The payer assesses the pair, not either half." }, { "code": "DIAGNOSIS_INTERVENTION_MISMATCH", "http": 422, "stop": "treat", "fix_stage": "clinical", "meaning": "The intervention is not supported by the diagnosis it was linked to under the payer's clinical rules.", "fix": "Read the detail block — it names both codes and the rule. Either the diagnosis is under-specified or the wrong intervention was chosen." }, { "code": "PRIMARY_DIAGNOSIS_CONFLICT", "http": 409, "stop": "treat", "fix_stage": "clinical", "meaning": "More than one diagnosis on the visit is ranked primary.", "fix": "Exactly one primary, any number of secondaries. Re-rank rather than deleting and re-recording." }, { "code": "DIAGNOSIS_LOCKED", "http": 409, "stop": "treat", "fix_stage": "clinical", "meaning": "A diagnosis was edited or withdrawn after the claim was submitted.", "fix": "The clinical record is amended, not rewritten. Raise the correction against the claim instead." }, { "code": "CLINICAL_BUNDLE_INVALID", "http": 400, "stop": "treat", "fix_stage": "clinical", "meaning": "The FHIR bundle failed validation — an unknown resource type, a missing subject, or a coding without its system.", "fix": "Read issues[]; each names the entry index and the element. A partially valid bundle is not partially written." }, { "code": "CLINICAL_CONSENT_MISSING", "http": 403, "stop": "treat", "fix_stage": "consent", "meaning": "The patient's proof does not extend to sharing the record beyond this facility, or to reading it back from elsewhere.", "fix": "Clinical sharing is its own purpose at the consent stop. Payer consent does not carry it, and neither is retroactive." }, { "code": "EPISODE_CLOSED", "http": 409, "stop": "treat", "fix_stage": "clinical", "meaning": "A visit was attached to an episode of care that has already been closed out.", "fix": "Open a new episode, or reopen the old one deliberately. A closed episode is a clinical statement, not a stale record." }, { "code": "ORDER_PERFORMER_UNREACHABLE", "http": 502, "stop": "treat", "fix_stage": "clinical", "meaning": "The facility the order was routed to did not accept it inside the rail's budget.", "fix": "The order is held and retried, not lost. Show it as routing rather than failed, and do not raise a second one." }, { "code": "RESULT_ORDER_MISMATCH", "http": 409, "stop": "treat", "fix_stage": "clinical", "meaning": "A result was returned with observations the order did not ask for, or missing ones it did.", "fix": "Return results against the expanded parameter list the order came back with, not against your own panel definition." }, { "code": "PRESCRIPTION_NOT_ROUTED_HERE", "http": 403, "stop": "treat", "fix_stage": "clinical", "meaning": "A dispense was attempted against a prescription routed to a different pharmacy.", "fix": "Dispense only from your own inbox. Where the patient walks in elsewhere, the prescription is re-routed rather than dispensed against." }, { "code": "DISPENSE_EXCEEDS_PRESCRIBED", "http": 409, "stop": "treat", "fix_stage": "clinical", "meaning": "The quantity dispensed, added to what was dispensed before, is more than was prescribed.", "fix": "Partial fills accumulate. Read what remains on the prescription rather than assuming the first dispense was the only one." }, { "code": "SUBSTITUTION_NOT_ALLOWED", "http": 409, "stop": "treat", "fix_stage": "clinical", "meaning": "A different product was dispensed against a prescription the prescriber marked no-substitution.", "fix": "The flag is set per item. Where the product is unavailable, route back to the prescriber instead of substituting." }, { "code": "DOCUMENT_DATA_INCOMPLETE", "http": 422, "stop": "treat", "fix_stage": "clinical", "meaning": "A document was requested that cannot be generated — the clinical data it renders from is missing fields.", "fix": "Read missing[]; each entry names the element. Record the clinical fact rather than writing the document by hand." }, { "code": "REFERRAL_AUTH_EXPIRED", "http": 409, "stop": "treat", "fix_stage": "consent", "meaning": "The authorisation taken at the source facility has passed its window before the patient arrived.", "fix": "Re-authenticate at the receiving facility. The window is on the authorisation the referral carried — surface it to the patient when they are referred, not when they arrive." }, { "code": "REFERRAL_NOT_ACCEPTED", "http": 409, "stop": "treat", "fix_stage": "clinical", "meaning": "A visit was opened against a referral the receiving facility has not accepted.", "fix": "Accept the referral first; acceptance is what opens the receiving visit against the source authorisation." }, { "code": "DIAGNOSIS_REQUIRED", "http": 400, "stop": "preauth", "fix_stage": "preauth", "meaning": "No primary diagnosis was supplied.", "fix": "Exactly one primary diagnosis is required, coded — never free text." }, { "code": "NARRATIVE_TOO_SHORT", "http": 400, "stop": "preauth", "fix_stage": "preauth", "meaning": "The clinical narrative is below the enforced minimum length.", "fix": "The narrative is read by a human reviewer. Treat the minimum as a floor, not a target." }, { "code": "DOCTOR_NOT_LICENSED", "http": 422, "stop": "preauth", "fix_stage": "preauth", "meaning": "The practitioner record has no active licence.", "fix": "Practitioner validity is checked live at submission. Codify practitioners from the registry rather than storing names." }, { "code": "MISSING_CLINICAL_FIELD", "http": 422, "stop": "preauth", "fix_stage": "preauth", "meaning": "A field required by this benefit type on this payer is absent or malformed.", "fix": "The message names the missing field. Requirements vary by benefit type and by payer." }, { "code": "INVALID_STATE_TRANSITION", "http": 409, "stop": "preauth", "fix_stage": "preauth", "meaning": "A message, cancellation or resubmission was attempted against a terminal reference.", "fix": "Only a returned request may be resubmitted, and it keeps its original reference." }, { "code": "UNMAPPED_CODE", "http": 422, "stop": "bill", "fix_stage": "mapping", "meaning": "The billing code does not resolve to a live item with a path to a payer revenue code.", "fix": "Declare the price-list item in mapping first. Anything undeclared stays off the claim entirely." }, { "code": "INVALID_CODE_COMBINATION", "http": 422, "stop": "bill", "fix_stage": "billing", "meaning": "The line conflicts with another active line on the visit.", "fix": "The message names both conflicting codes. Order matters — ask before adding where your workflow allows." }, { "code": "LINE_NOT_RETIRABLE", "http": 409, "stop": "bill", "fix_stage": "billing", "meaning": "Retirement was attempted on a per-diem line outside a level change.", "fix": "Move per-diem lines through a level change. Editing is not a supported operation." }, { "code": "RESERVATION_EXCEEDED", "http": 409, "stop": "bill", "fix_stage": "billing", "meaning": "The amount requested exceeds what is available at the moment of the call.", "fix": "Re-read the item's balance. It may have been consumed elsewhere since eligibility." }, { "code": "ALREADY_RESERVED", "http": 409, "stop": "bill", "fix_stage": "billing", "meaning": "A reservation already exists for this code on this visit.", "fix": "Release the existing reservation with a reason and create a fresh one. Nothing is overwritten silently." }, { "code": "PHARMACY_NOT_PAYABLE", "http": 403, "stop": "bill", "fix_stage": "billing", "meaning": "The product is not reimbursable or is not registered.", "fix": "It may still be sold as cash. This is a payability answer, not a dispensing one." }, { "code": "NOT_READY", "http": 422, "stop": "submit", "fix_stage": "submission", "meaning": "Close was called while pre-flight still reports blockers.", "fix": "Run pre-flight and resolve every blocker-severity reason first." }, { "code": "MISSING_DOCUMENTS", "http": 422, "stop": "submit", "fix_stage": "billing", "meaning": "A document required by a billed item has not been attached.", "fix": "The required document list was returned with the item at eligibility. Attach as captured, not at the end." }, { "code": "NEEDS_REVIEW", "http": 200, "stop": "submit", "fix_stage": "authorization", "meaning": "Warning, not a blocker — an override was applied earlier without confirmation.", "fix": "It does not stop billing, but it cannot ride through to submission unexamined. Someone must confirm it." }, { "code": "CALLBACK_NOT_REGISTERED", "http": 409, "stop": "submit", "fix_stage": "authentication", "meaning": "No callback registration exists for claim decisions.", "fix": "Register callbacks at onboarding, not when you first need them." }, { "code": "CLAIM_DATE_OUT_OF_COVER", "http": 409, "stop": "submit", "fix_stage": "cover", "meaning": "A billed date falls outside the selected cover's validity window.", "fix": "Check the service dates against the cover chosen at the start of the visit." }, { "code": "RESERVATION_MISSING", "http": 409, "stop": "submit", "fix_stage": "billing", "meaning": "A line has no active reservation at discharge time.", "fix": "Return to billing. Every unretired line must trace to a reservation." }, { "code": "ALREADY_CLOSED", "http": 409, "stop": "submit", "fix_stage": "submission", "meaning": "Discharge was attempted on a visit that is already closed.", "fix": "Treat as success if your own state is behind; do not open a second visit." }, { "code": "UNKNOWN_EVENT", "http": 400, "stop": "reconcile", "fix_stage": "authentication", "meaning": "The callback registration contains an event name the rail does not publish.", "fix": "Register only published event names. Unknown values are rejected outright." } ] }