Error Handling

NHIE services do not share a single error format. How a failure is reported depends on where it happened: at the gateway, in a FHIR service, or in an HL7 v2 or CSD service. This page explains how to recognise each kind of error, what to do about it, and what to capture when you need support.

Where errors come from

Layer	Services	How the error is reported
Connection (TLS)	All mTLS endpoints	The TLS handshake fails. No HTTP response is returned.
Gateway	All services	An HTTP status with a short JSON message, or an HTML error page for unknown routes
FHIR services	HPRS PDQm (`/pdqm`, `/mtlspdqm`), ARR (`/arr/AuditEvent`)	An HTTP status with a FHIR `OperationOutcome` body
HL7 v2 services	HPRS PDQ (`/pdq`)	An HL7 acknowledgment code in `MSA-1` and `QAK-2`, with details in the `ERR` segment
CSD services	MHFL (`/csd`)	CSD XML on success. Some query errors return a plain-text error trace instead.

Check the layer first. A TLS failure or a gateway 401 or 403 means the request never reached the service, so changing the payload will not help.

Status codes

Status	Meaning on NHIE	What to do
`400 Bad Request`	Missing or malformed search parameter, unsupported identifier type code, or an `mr` identifier system without a facility code	Fix the request. Do not retry unchanged.
`401 Unauthorized`	Missing or invalid `apikey` header (MHFL)	Check the header name and value.
`403 Forbidden`	Missing or incomplete `x-security` header (HPRS), IP address not whitelisted, or credentials that do not cover the route	Check the `x-security` header. If it is correct, contact HIS Support.
`404 Not Found`	No patient matched the identifier, or the request reached the gateway without a service path	For a patient lookup, treat it as a valid "no match" result. For the base URL, call a service endpoint.
`422 Unprocessable Entity`	The request is well formed but fails a business rule, such as an invalid South African ID number check digit or a patient `id` sent with an identifier	Correct the data. Do not retry unchanged.
`429 Too Many Requests`	Throttling applied to protect shared use of the test environment	Wait, then retry with backoff.
`5xx`	Service or upstream failure	Retry read operations with backoff. Escalate if the error persists.

HPRS errors

PDQm (FHIR)

HPRS PDQm returns errors as a FHIR OperationOutcome. The human-readable reason is in issue[].details.text, and a machine-readable code is in issue[].details.coding[].code.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "coding": [
          {
            "system": "https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1",
            "code": "INVALID_PARAMETER",
            "display": "Invalid parameter"
          }
        ],
        "text": "Invalid RSA identification number."
      }
    }
  ]
}

Scenario	Response
Patient does not exist	`404 Not Found`, operation outcome "patient not found"
No `x-security` header	`403 Forbidden`, "Missing security header"
`x-security` header without a user ID (`x-security: emr$`)	`403 Forbidden`, "Missing account id in security header"
`$match` request without a security segment or security header	`403 Forbidden`, "missing security segment"
Empty or missing `identifier` parameter	`400 Bad Request`, "Invalid parameter"
Unsupported identifier type code (for example `PRV`)	`400 Bad Request`, "Invalid identifier type code"
`mr` identifier system without a facility code	`400 Bad Request`, "Invalid identifier system required `https://test-hie.health.gov.za/mr/<facilitycode>`"
South African ID number fails validation	`422 Unprocessable Entity`, "Invalid RSA identification number."
Request contains both a patient `id` and an identifier	`422 Unprocessable Entity`, `CONFLICTING_VALUES`
Unsupported resource path (for example `/pdqm/Location`)	An HTML error page: `Cannot GET /pdqm/Location`

South African ID numbers are validated before the search runs: 13 digits, starting with a valid YYMMDD date, and ending with a valid check digit. Validate them in your own system first to avoid avoidable 422 responses.

See PDQm for the full request and response examples.

PDQ (HL7 v2)

HPRS PDQ always returns an HL7 message. Read the outcome from the acknowledgment codes, not from the HTTP status.

`MSA-1`	`QAK-2`	Meaning	What to do
`AA`	`OK`	One or more patients found	Process the `PID` segments.
`AA`	`NF`	Query accepted, no patients found	Treat as a valid "no match" result.
`AE`	`AE`	Application error	Read the `ERR` segment, correct the query, and resend.
`AR`	—	Application reject	Read the `ERR` segment. Check the message structure and header fields.

MSA|AE|TEST-CR-14-30
ERR||QPD^1^3^2|204|E||||unknown domain namespace id
QAK|8494764101303661668890645833527|AE

In this example, ERR-2 (QPD^1^3^2) points to the field that caused the error, and ERR-8 gives the reason: the assigning authority in the query is not a known identifier domain.

See PDQ (HL7 v2) for more examples.

MHFL errors

Scenario	Response
Missing or invalid `apikey` header	`401 Unauthorized` with `{"message":"Invalid authentication credentials"}`
Paged search where `max` is larger than the result set	A plain-text error trace containing `[FOER0000] The collection size is not greater or equal to the max value!`

Because some MHFL errors are returned as plain text, check that the response body is CSD XML before you parse it. Never show the raw error trace to end users.

See the MHFL API Guide for the supported search modes.

ARR errors

The ARR is a FHIR endpoint, so failures are returned as an OperationOutcome with an HTTP error status. A successful submission returns the stored AuditEvent with its assigned id.

If the ARR cannot be reached, keep the audit record and send it later. The HPRS guide requires audit records to be buffered locally until connectivity is restored. Do not drop them, and do not block the clinical workflow while you wait.

Handling errors in code

Choose a parser based on the response Content-Type. An error body may be FHIR JSON, plain JSON, HTML, or plain text.

JavaScript
Python

async function readNhieError(response) {
  const contentType = response.headers.get('content-type') || '';
  const text = await response.text();

  if (contentType.includes('json')) {
    try {
      const body = JSON.parse(text);

      if (body.resourceType === 'OperationOutcome') {
        const issue = body.issue?.[0] ?? {};
        return {
          code: issue.details?.coding?.[0]?.code ?? issue.code,
          message: issue.details?.text ?? issue.diagnostics ?? 'Request failed',
        };
      }

      return { code: null, message: body.message ?? 'Request failed' };
    } catch {
      // Fall through and treat the body as text.
    }
  }

  // HTML pages and plain-text traces are for logs only.
  return { code: null, message: `Request failed with status ${response.status}` };
}

async function requestNhie(url, options, context) {
  const response = await fetch(url, options);

  if (response.ok) {
    return response;
  }

  const { code, message } = await readNhieError(response);

  console.error('NHIE request failed', {
    service: context.service,
    method: options.method ?? 'GET',
    path: new URL(url).pathname,
    status: response.status,
    code,
    message,
    timestamp: new Date().toISOString(),
  });

  const error = new Error(message);
  error.status = response.status;
  error.code = code;
  throw error;
}

import logging
from datetime import datetime, timezone
from urllib.parse import urlparse

import requests

log = logging.getLogger("nhie")


class NhieError(Exception):
    def __init__(self, status, code, message):
        super().__init__(message)
        self.status = status
        self.code = code


def read_nhie_error(response):
    content_type = response.headers.get("content-type", "")

    if "json" in content_type:
        try:
            body = response.json()
        except ValueError:
            body = {}

        if body.get("resourceType") == "OperationOutcome":
            issue = (body.get("issue") or [{}])[0]
            details = issue.get("details", {})
            coding = (details.get("coding") or [{}])[0]
            return (
                coding.get("code") or issue.get("code"),
                details.get("text") or issue.get("diagnostics") or "Request failed",
            )

        if body.get("message"):
            return None, body["message"]

    # HTML pages and plain-text traces are for logs only.
    return None, f"Request failed with status {response.status_code}"


def request_nhie(method, url, service, **kwargs):
    response = requests.request(method, url, timeout=30, **kwargs)

    if response.ok:
        return response

    code, message = read_nhie_error(response)
    log.error(
        "NHIE request failed",
        extra={
            "service": service,
            "method": method,
            "path": urlparse(url).path,
            "status": response.status_code,
            "code": code,
            "error_message": message,
            "timestamp": datetime.now(timezone.utc).isoformat(),
        },
    )
    raise NhieError(response.status_code, code, message)

For HPRS PDQ (HL7 v2), check the acknowledgment codes instead of the HTTP status:

function readPdqAck(hl7Message) {
  const segments = hl7Message.split(/\r\n|\r|\n/);
  const field = (name, index) =>
    segments.find((segment) => segment.startsWith(`${name}|`))?.split('|')[index];

  return {
    ackCode: field('MSA', 1),        // AA, AE, or AR
    queryStatus: field('QAK', 2),    // OK, NF, or AE
    errorText: field('ERR', 8) ?? null,
  };
}

Retries

Retry only when the failure is temporary and the request is safe to repeat.

Failure	Retry?
`429 Too Many Requests`	Yes, with exponential backoff and jitter
`5xx` on a query (PDQ, PDQm, CSD)	Yes, with backoff, up to a small limit
Network timeout or connection reset on a query	Yes, with backoff
ARR unavailable	Buffer the audit record locally and resend when the ARR is reachable
TLS handshake failure	No. Check your certificate, key, and CA bundle.
`400`, `401`, `403`, `404`, `422`	No. Fix the cause first.
HL7 `AE` or `AR`	No. Fix the query first.

Retry example
Implementation guidance

const RETRIABLE_STATUSES = new Set([429, 500, 502, 503, 504]);

async function withBackoff(requestFn, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    try {
      return await requestFn();
    } catch (error) {
      // Network errors have no status and are treated as retriable.
      const isRetriable = error.status === undefined || RETRIABLE_STATUSES.has(error.status);

      if (!isRetriable || attempt === maxAttempts) {
        throw error;
      }

      const delayMs = 500 * 2 ** (attempt - 1) + Math.random() * 250;
      await new Promise((resolve) => setTimeout(resolve, delayMs));
    }
  }
}

Log the attempt number and service name with each retry.
Reuse the same HL7 message control ID (MSH-10) when you resend a PDQ query, so retries can be matched in logs.
Send an ATNA audit event for each query that reaches HPRS, including failed ones, with the correct outcome code.
Show a final message to the user only after retries are exhausted.

Cross-service workflows

A clinical workflow usually touches more than one service. Check each dependency in order, so a failure points to one cause.

Connection and credentials. Confirm the mTLS handshake succeeds and the apikey or x-security header is accepted.
Patient identity (HPRS). Search HPRS before any further processing. A 404 or NF result means no match, not a failure.
Facility (MHFL). Confirm the facility code exists and the facility status is Active.
Audit (ARR). Send the ATNA audit event for the transaction. If the ARR is unavailable, buffer it locally.

If HPRS itself is unavailable (connection failures or repeated 5xx responses), your system may create the patient locally. When HPRS is available again, update the local record with HPRS demographics using a PDQ query. See the minimum requirements for third-party applications.

User-facing messages

Keep messages short, specific, and free of internal detail. Never show stack traces, raw HL7, or identifiers that are not already on screen.

Condition	Message to show
Patient not found in HPRS	`No patient matched this identifier. Check the number or register the patient.`
Invalid South African ID number	`This ID number is not valid. Check the digits and try again.`
Missing or rejected security header	`Patient lookup is not available for your account. Contact your system administrator.`
Invalid MHFL API key	`Facility lookup is not configured correctly. Contact your system administrator.`
Rate limit reached	`The service is busy. Wait a moment and try again.`
HPRS or MHFL unavailable	`The national registry is not responding. You can continue, and the record will be updated later.`

Logging

Log the timestamp, service, HTTP method, path, status, and error code for every failed call.
For HPRS PDQ, log the message control ID (MSH-10) and query tag (QPD-2).
For the ARR, log the id returned for each stored AuditEvent.
Never log the apikey value, private keys, or certificate files.
Patient identifiers and demographics are personal information under POPIA. Mask them in application logs. Your ATNA audit events are the record of who accessed which patient.

Support checklist

When you contact HIS Support, include:

Environment: test or production
Service and endpoint, for example HPRS PDQm GET /pdqm/Patient
HTTP method and the time of the request, with time zone
HTTP status and the full error body (OperationOutcome, HL7 MSA, ERR and QAK segments, or the error text)
The request with secrets removed and patient identifiers replaced by test values
Your source IP address, if you see a 403 or a TLS failure
Whether the problem happens every time or only sometimes