Participant receives an error report

Hosted by every participant. The exchange posts this message to the endpoint_URL you registered, at /v1/error, with the headers and the sealed payload the sender posted.

POST/v1/error

Answer HTTP 202 with the receipt first and process afterwards; Receiving a callback has the rules.

Where the exchange tells a sender that a request could not be delivered after five attempts. Received by every participant under its registered address. There is no outbound form.

Authorizations

bearer_authapiKeyRequired

Every NHCX call carries the access token from the session call in a header named bearer_auth, as the word Bearer, a space and the token. NHCX reads bearer_auth, not Authorization.

Example Bearer <access token>

Protected header

These fields go in the JWE protected header of payload, not as HTTP headers. Building and sending a JWE shows how to prepare and encrypt the payload, and Receiving a callback how to decrypt one.

algstringRequired

Key management algorithm. Always RSA-OAEP-256: the content key is wrapped with the recipient's RSA public key.

Example RSA-OAEP-256

encstringRequired

Content encryption algorithm. Always A256GCM.

Example A256GCM

x-hcx-sender_codestringRequired

Your participant code. Mandatory on the envelope.

Example nhcx-gateway@hcx

x-hcx-recipient_codestringRequired

The recipient's. For a provider, the processor code from the policy lookup. Mandatory on the envelope.

Example <provider participant code>

x-hcx-api_call_idstringRequired

Fresh on every message, including responses. Mandatory on the envelope.

Example <uuid>

x-hcx-correlation_idstringRequired

The thread that ties a request to its answers. The correlation ID rule says when to reuse it. Mandatory on the envelope.

Example <correlation id>

x-hcx-timestampstringRequired

The time the message was made. Timestamp gives the format. Mandatory on the envelope.

Example <iso timestamp>

x-hcx-statusstringRequired

Where this message stands. Status words lists the values. Mandatory on the envelope.

Example response.error

Body

typestring

x-hcx-sender_codestring

x-hcx-recipient_codestring

x-hcx-api_call_idstring

x-hcx-correlation_idstring

x-hcx-workflow_idstring

x-hcx-timestampstring

x-hcx-statusstring

x-hcx-error_detailsobject

x-hcx-error_details.codestring

x-hcx-error_details.messagestring

x-hcx-error_details.tracestring

x-hcx-entity-typestring

Responses

202

Received. The receipt names the message it answers; the answer itself follows as a call of your own.

timestampstring

api_call_idstring

correlation_idstring

resultobject

result.sender_codestring

result.recipient_codestring

result.entity_typestring

result.protocol_statusstring

errorobject

error.codestring

error.messagestring

curl --request POST \
  --url {bridgeUrl}/v1/error \
  --header 'bearer_auth: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "ProtocolResponse",
  "x-hcx-sender_code": "nhcx-gateway@hcx",
  "x-hcx-recipient_code": "<provider participant code>",
  "x-hcx-api_call_id": "<uuid>",
  "x-hcx-correlation_id": "<correlation id>",
  "x-hcx-workflow_id": "12",
  "x-hcx-timestamp": "<iso timestamp>",
  "x-hcx-status": "response.error",
  "x-hcx-error_details": {
    "code": "ERR_DELIVERY_FAILED",
    "message": "Recipient endpoint unreachable after five attempts",
    "trace": ""
  },
  "x-hcx-entity-type": "preauth"
}'

Participant codes, ABHA numbers, tokens and payloads in these examples are placeholders, never real credentials or patient data.

{
  "timestamp": "04/09/2026 11:46:41:305",
  "api_call_id": "<from the incoming header>",
  "correlation_id": "<from the incoming header>",
  "result": {
    "sender_code": "1000003538@hcx",
    "recipient_code": "<provider participant code>",
    "entity_type": "preauth",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}

Where this fits

NHCX sends this message to the participant itself: NHCX: report a request it could not deliver.