Skip to main content

NHCX: report a request it could not deliver

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.

POST/v1/error

Business purpose

When the exchange cannot deliver a request, it tries five times, retires the correlation ID and tells the original sender here. A system without this endpoint never learns that its request died, and a dead request looks exactly like a case still under review. Every participant must host it.

When to use

You host this path and never call it. Providers and payers both need it, so build it first.

Preconditions

  • Your callback URL is registered: a domain name over HTTPS, hosted in India, answering within 30 seconds.
  • Your handler accepts a body it does not know. The report is plain JSON, not encrypted.

Postconditions

Answer 202. The original request is dead, so a retry needs a new correlation ID.

Common mistakes

  • Not hosting it, so failed deliveries go unseen.
  • Rejecting the report because it does not match a fixed schema.
  • Retrying the failed request on the old correlation ID.

Best practices

  • Store the report whole before doing anything with it.
  • Mark the case it names as undelivered, so the desk does not wait for a decision that will not come.
  • Check it first when a case goes quiet, before asking the exchange with /v1/status.

Related scenario

A hospital posts a pre-authorisation and gets its receipt, but the payer's endpoint is down. The exchange tries five times, retires the correlation ID and posts a report to the hospital's /v1/error. The handler stores the report whole, answers 202 with the receipt, and marks the pre-authorisation undelivered. The desk resubmits it with a fresh correlation ID once the payer is reachable.

Specification

Chapter Building and sending a JWE of the NHCX integration specification.

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

200

Answer 202 with the receipt, like every other delivery, filling in whatever identifiers the report carries and leaving the rest empty.

timestampstring
api_call_idstring
correlation_idstring
resultobject
result.sender_codestring
result.recipient_codestring
result.entity_typestring
result.protocol_statusstring
errorobject
error.codestring
error.messagestring

Callbacks​