{
  "resourceType": "ValueSet",
  "id": "rail-errors",
  "url": "https://terminology.example.co.ke/ValueSet/rail-errors",
  "version": "2026-08-14.1",
  "name": "RailErrorCodes",
  "title": "Unified Payer API error codes",
  "status": "active",
  "description": "All error codes returned by the Unified Payer API.",
  "compose": {
    "include": [
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors"
      }
    ]
  },
  "expansion": {
    "total": 68,
    "contains": [
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "UNAUTHENTICATED",
        "display": "No token, an expired token, or a token the rail does not recognise."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "FACILITY_CONTEXT_MISSING",
        "display": "The facility headers were absent, so no facility-scoped rule could be resolved."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "OUTSIDE_FACILITY_GEOFENCE",
        "display": "The call originated outside the configured radius of the facility. Checked before any stop-specific gate."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "MEMBER_NOT_FOUND",
        "display": "The identifier does not resolve to any registry record."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "IDENTIFIER_CONFLICT",
        "display": "The identifier matches more than one record and cannot be disambiguated automatically."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "IDENTIFIER_TYPE_REQUIRED",
        "display": "An identifier value arrived without its type. A number on its own resolves to nothing."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "IDENTIFIER_TYPE_UNKNOWN",
        "display": "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."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "REGULATOR_REQUIRED",
        "display": "A practitioner was searched by registration number with no regulator. The same digits can be valid under more than one council."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "PRACTITIONER_NOT_FOUND",
        "display": "No practitioner matches that regulator and registration number."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "MEMBER_DECEASED",
        "display": "The record resolved, but the registry reports the person as deceased (is_alive: false)."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "REGISTRY_TIMEOUT",
        "display": "The client registry did not answer inside the rail's budget. The lookup may still complete."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "COVER_INVALID",
        "display": "The cover does not resolve, or its status is not active."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "COVER_EXPIRED",
        "display": "The cover's policy window does not include today."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "SCHEME_CODE_REQUIRED",
        "display": "The cover is live on more than one scheme and no scheme was named in the selection."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "ELIGIBILITY_REF_NOT_FOUND",
        "display": "The eligibility reference is unknown or has expired."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "PAYER_UNREACHABLE",
        "display": "The payer did not respond within the configured timeout."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "CONSENT_REQUIRED",
        "display": "An operation that reads or acts on a member's record was attempted without a recorded consent."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "CALLBACK_URL_REQUIRED",
        "display": "A consent session was opened with nowhere to deliver its outcome."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "METHODS_NOT_CLIENT_DECLARED",
        "display": "The open call tried to specify which consent factors to use."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "CONSENT_PURPOSE_INVALID",
        "display": "purpose is not one of the published values."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "EMBED_ORIGIN_NOT_REGISTERED",
        "display": "The page attempting to frame the consent UI is served from an origin the rail does not know."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "SUBJECT_NOT_CONSENTABLE",
        "display": "No consent can be taken for this person — most often a deceased record."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "NO_FACTOR_AVAILABLE",
        "display": "Nothing can legally prove consent for this member, at this facility, right now."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "CONSENT_SESSION_PENDING",
        "display": "An earlier consent session is still open, which blocks creating a new one."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "CONSENT_SESSION_EXPIRED",
        "display": "The session outlived its window before it was completed."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "CHALLENGE_REJECTED",
        "display": "A wrong or expired code, or attempts exhausted."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "PAYER_METHOD_BLOCKED",
        "display": "The requested factor is disabled for this payer and was never offered."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "HARDWARE_MISMATCH",
        "display": "The capture device does not match this workstation's registration."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "NO_LOCATION_ASSIGNED",
        "display": "A visit was opened before a service location was set."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "BENEFIT_EXHAUSTED",
        "display": "The item's balance or counters were consumed — possibly elsewhere, between eligibility and now."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "WAITING_PERIOD",
        "display": "The benefit's waiting window has not yet elapsed."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "VISIT_ALREADY_OPEN",
        "display": "Another active visit of the same class exists for this member."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "DIAGNOSIS_REQUIRED",
        "display": "The visit has no recorded diagnosis, and something downstream — a preauthorisation, a claim — needs one."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "DIAGNOSIS_CODE_INVALID",
        "display": "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."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "DIAGNOSIS_NOT_LINKED",
        "display": "A diagnosis was recorded without the intervention it justifies, or a billed intervention has no diagnosis behind it."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "DIAGNOSIS_INTERVENTION_MISMATCH",
        "display": "The intervention is not supported by the diagnosis it was linked to under the payer's clinical rules."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "PRIMARY_DIAGNOSIS_CONFLICT",
        "display": "More than one diagnosis on the visit is ranked primary."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "DIAGNOSIS_LOCKED",
        "display": "A diagnosis was edited or withdrawn after the claim was submitted."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "CLINICAL_BUNDLE_INVALID",
        "display": "The FHIR bundle failed validation — an unknown resource type, a missing subject, or a coding without its system."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "CLINICAL_CONSENT_MISSING",
        "display": "The patient's proof does not extend to sharing the record beyond this facility, or to reading it back from elsewhere."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "EPISODE_CLOSED",
        "display": "A visit was attached to an episode of care that has already been closed out."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "ORDER_PERFORMER_UNREACHABLE",
        "display": "The facility the order was routed to did not accept it inside the rail's budget."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "RESULT_ORDER_MISMATCH",
        "display": "A result was returned with observations the order did not ask for, or missing ones it did."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "PRESCRIPTION_NOT_ROUTED_HERE",
        "display": "A dispense was attempted against a prescription routed to a different pharmacy."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "DISPENSE_EXCEEDS_PRESCRIBED",
        "display": "The quantity dispensed, added to what was dispensed before, is more than was prescribed."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "SUBSTITUTION_NOT_ALLOWED",
        "display": "A different product was dispensed against a prescription the prescriber marked no-substitution."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "DOCUMENT_DATA_INCOMPLETE",
        "display": "A document was requested that cannot be generated — the clinical data it renders from is missing fields."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "REFERRAL_AUTH_EXPIRED",
        "display": "The authorisation taken at the source facility has passed its window before the patient arrived."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "REFERRAL_NOT_ACCEPTED",
        "display": "A visit was opened against a referral the receiving facility has not accepted."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "DIAGNOSIS_REQUIRED",
        "display": "No primary diagnosis was supplied."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "NARRATIVE_TOO_SHORT",
        "display": "The clinical narrative is below the enforced minimum length."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "DOCTOR_NOT_LICENSED",
        "display": "The practitioner record has no active licence."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "MISSING_CLINICAL_FIELD",
        "display": "A field required by this benefit type on this payer is absent or malformed."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "INVALID_STATE_TRANSITION",
        "display": "A message, cancellation or resubmission was attempted against a terminal reference."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "UNMAPPED_CODE",
        "display": "The billing code does not resolve to a live item with a path to a payer revenue code."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "INVALID_CODE_COMBINATION",
        "display": "The line conflicts with another active line on the visit."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "LINE_NOT_RETIRABLE",
        "display": "Retirement was attempted on a per-diem line outside a level change."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "RESERVATION_EXCEEDED",
        "display": "The amount requested exceeds what is available at the moment of the call."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "ALREADY_RESERVED",
        "display": "A reservation already exists for this code on this visit."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "PHARMACY_NOT_PAYABLE",
        "display": "The product is not reimbursable or is not registered."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "NOT_READY",
        "display": "Close was called while pre-flight still reports blockers."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "MISSING_DOCUMENTS",
        "display": "A document required by a billed item has not been attached."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "NEEDS_REVIEW",
        "display": "Warning, not a blocker — an override was applied earlier without confirmation."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "CALLBACK_NOT_REGISTERED",
        "display": "No callback registration exists for claim decisions."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "CLAIM_DATE_OUT_OF_COVER",
        "display": "A billed date falls outside the selected cover's validity window."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "RESERVATION_MISSING",
        "display": "A line has no active reservation at discharge time."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "ALREADY_CLOSED",
        "display": "Discharge was attempted on a visit that is already closed."
      },
      {
        "system": "https://terminology.example.co.ke/CodeSystem/rail-errors",
        "code": "UNKNOWN_EVENT",
        "display": "The callback registration contains an event name the rail does not publish."
      }
    ]
  }
}