10 Common NHCX Integration Mistakes (From NHA's Own Documentation)

NHA maintains a document on the NHCX sandbox portal that few integrators ever find: "Common Mistakes while implementing through NHCX." Combined with the API-response-handling guide and the standard error-code sheets (updated August 2026), it's effectively the examiner publishing the answer key.

Here are the ten mistakes — from NHA's own documentation plus what surfaces in the developer community — with the fix for each. If you're starting from zero, read our NHCX onboarding checklist first.

1. Reusing a Correlation ID After an Error

The correlation ID ties a request to its async callback. NHA's rule: on any error or failure, that correlation ID is made inactive in the NHCX system — retrying with the same UUID silently goes nowhere. Every fresh request cycle needs a fresh UUID. If you've integrated ABDM, this will feel familiar: it's the same strictness as the REQUEST-ID correlation rules on ABDM callbacks.

2. Ignoring the 5-Retry-Then-Delete Rule

When a recipient rejects a payload — wrong format, decryption failure, protocol error — NHCX retries delivery up to five times, then deletes the request for that correlation ID. If your callback endpoint was down or erroring during those attempts, the request is gone; there is no replay. Your on_* endpoints need availability monitoring, and your state machine needs a timeout path that triggers a status check rather than waiting forever.

3. Wrong Protocol Response Shape (It's Always 202)

Every request you receive through NHCX must be answered synchronously with HTTP 202 Accepted plus the protocol body — timestamp, api_call_id, correlation_id, sender/recipient codes, entity type, and protocol status. Returning 200, an empty body, or your own JSON shape counts as a protocol error (see mistake #2 for what happens next).

4. Malformed Protocol Headers

The JWE protected header carries the routing and audit metadata: alg (RSA-OAEP-256), enc (A256GCM), and the x-hcx set — x-hcx-api_call_id, x-hcx-workflow_id, x-hcx-request_id, x-hcx-status, x-hcx-timestamp (epoch milliseconds), x-hcx-sender_code, x-hcx-recipient_code, x-hcx-correlation_id, and x-hcx-ben-abha-id. Missing or misnamed headers are one of the top rejection causes NHA lists.

5. Using the Wrong Registry ID in Production

Providers pass their HFR ID as the registry ID. Payers and TPAs pass their IRDAI-issued number — with leading zeros stripped (0123 becomes 123). Mixed-up registry IDs cause rejections and misrouted transactions that look like mysterious payer silence.

6. Missing Accept and Content-Type Headers

Trivial but on NHA's list for a reason: every call needs Accept: application/json, Content-Type: application/json, and the bearer token header. SDKs and generated clients sometimes drop the Accept header — and the gateway cares.

7. Routing Claims to the PayerID Instead of the ProcessingID

The subtlest one in the list: after calling get/Policies for a beneficiary, providers naturally reach for the payerID in the response as the recipient. Wrong — the receiver code must be the processingID from the get/Policies response. Route to the payerID and your requests go to the wrong place.

8. Treating a 401 as a Bug Instead of an Expired Token

Session tokens come from the ABDM gateway sessions API and expire. A 401 "sender is not authorized" mid-integration almost always means the token lapsed: generate a fresh token and retry before debugging anything else.

9. Policy Linking Without the Right Identity

ABHA-policy linking and delinking are auth-restricted: only the entities named in the payerID and policyID at link time are authorized, and the token must be generated with the same client ID used at participant creation. Get this wrong and you hit HCP057 ("user unauthorised to link policies") — currently one of the most-asked unresolved questions in the NHCX community. If identities don't match, NHA asks you to confirm over email; budget time for that loop.

10. Handling Only the Happy-Path Callback

Every on_* callback arrives in one of two shapes, discriminated by the type parameter: an RFC 7516 JWE-encrypted FHIR bundle (payer processed your request) or a plain ProtocolResponse (the payload failed validation or decryption). Callback handlers written for only the encrypted shape crash or mis-log exactly when you most need diagnostics. Implement both branches, plus the v1/error notification so the sender learns when a request never reached the recipient.

Bonus: The Payer Isn't Ignoring You — Read the Error Codes

NHA publishes standard error-code sheets: PAYR-1001 to 1020 for business rejections (policy expired, coverage insufficient, claim exceeds pre-auth amount, duplicate claim by service codes and dates, submission window expired) and NHCX-100x for transport errors (sender/receiver not registered, duplicate correlation ID, invalid headers). Wire these into your engine as first-class states — "rejected because PAYR-1012" is actionable by your billing team; "payer said no" is not. And before you can decode any of it, your bundles must pass NRCES profile validation — the same discipline as ABDM M2, where profile misses show up as NA fields.

We build claims integrations with these traps handled in the framework layer — envelope, correlation lifecycle, callback duality, and error-code mapping — so your team writes claim logic, not protocol plumbing. Explore our Healthcare Interoperability Solutions and revenue cycle engineering services, or talk to our team.