Skip to main content

Other

Error report (callback)

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

Hosted, never called. Implement it before anything else that is asynchronous. Providers and payers both host it.

### Preconditions

- Your callback address is registered: a domain name over HTTPS with TLS 1.2 or newer, hosted in India, reachable from the exchange's outbound addresses and answering within 30 seconds. - The handler accepts a body it does not recognise. What arrives is a plain JSON report of the request the exchange gave up on, with the rejection details, not a sealed JWEPayload. Its field names are not published, so the body in this request is an illustration rather than a schema.

### Postconditions

Answer 202 with the receipt, like every other delivery, filling in whatever identifiers the report carries and leaving the rest empty. The original request is dead: its correlation ID has been retired, so a retry needs a fresh one.

### Common mistakes

- Not hosting it, so failed deliveries are never seen. - Parsing the report against a fixed schema and answering 4xx when it does not match. - Retrying the failed request on the retired 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](/docs/nhcx/v1/getting-started/building-and-sending-a-jwe) of the NHCX integration specification.

Authorizations

Authorizationbearer tokenRequired

On every NHCX call, the token goes in a header called bearer_auth, with the word Bearer and a space in front. The sources are not unanimous: the authentication page and the FAQ both write the example as Authorization, and the notification endpoint uses Authorization. The safe course, and what the adapter does, is to send both headers with the same value.

Headers

bearer_authstringRequired

It is bearer_auth, not Authorization, on NHCX's own endpoints.

x-hcx-sender_codestringRequired

Your participant code. Mandatory on the envelope.

x-hcx-recipient_codestringRequired

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

x-hcx-api_call_idstringRequired

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

x-hcx-correlation_idstringRequired

The thread. See the rule below. Mandatory on the envelope.

x-hcx-timestampstringRequired

See the format note below. Mandatory on the envelope.

x-hcx-statusstringRequired

Where this message stands. Values below. Mandatory on the envelope.

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.

Callbacks​

  • After this call, ABDM posts Receive error report (callback) to v1_error. Open the callback.