Common Mistakes

Fix common NHCX integration mistakes before sandbox and production tests.

Use this page as a pre-test checklist. Resolve each issue before you send a request through NHCX.

Mistakes and resolutions

Mistake	Resolution
The request uses the wrong `x-hcx-status` value.	Use `request.initiate` for an initial request. Use `response.complete`, `response.partial`, or `response.error` for a response.
The integrator does not handle error scenarios.	Implement the `/v1/error` API. See API Response Handling.
The protocol response has the wrong HTTP code.	Return HTTP `202 Accepted` for each request.
The protocol response body has the wrong shape.	Use the acceptance response body from API Response Handling.
The protected header misses required NHCX fields.	Send all required protocol headers in the JWE protected header.
The production registry ID has the wrong value.	Use the HFR ID for a provider. Use the IRDAI registry ID for a payer.
The payer registry ID keeps a left zero.	Remove the left zero. Send `123` instead of `0123`.
The API call misses the `Accept` header.	Send `Accept: application/json`.
The API call misses the content type.	Send `Content-Type: application/json`.
The API call misses the auth header.	Send `bearer_auth: ******` with a valid token.
The provider uses the payer ID from `getPolicy`.	Use `processingID` from the `get/policies` response as the receiver code.
The request reuses a correlation ID.	Generate a unique UUID for each request cycle.
The integrator retries after a failed correlation ID.	Start a fresh request with a new correlation ID.
The API returns `401 Unauthorized`.	Generate a new token and retry with that token.
A policy link or delink call fails auth.	Use the client ID that created the payer ID and policy ID.

Required headers

Send these HTTP headers with each relevant NHCX API call.

HTTP headers

Accept: application/json
Content-Type: application/json
bearer_auth: ******

Protected header example

Use these fields in the JWE protected header. Generate new UUID values for each request cycle.

Protected header fields

{
  "alg": "RSA-OAEP-256",
  "enc": "A256GCM",
  "x-hcx-api_call_id": "961b29bc-72fa-45fe-8735-xxxxxxxx3e3b",
  "x-hcx-workflow_id": "33",
  "x-hcx-request_id": "eb1b2d8c-xxxx-438b-xxxx-8313875da3c9",
  "x-hcx-status": "request.initiate",
  "x-hcx-timestamp": "1723529473885",
  "x-hcx-sender_code": "PYRxx@hcx",
  "x-hcx-recipient_code": "INxxx@hcx",
  "x-hcx-correlation_id": "17301a2d-fb34-4bf1-xxxx-bfxxxxxxx310",
  "x-hcx-ben-abha-id": ""
}

Pre-test checklist

Check the status value

Select the status from Workflow Status Codes.

Check the IDs

Generate new UUID values for the API call, request, and correlation IDs.

Check the registry ID

Use the correct registry ID for the participant type.

Check the response

Return HTTP 202 Accepted with the required response body.

Check token freshness

Generate a new token when any API returns 401 Unauthorized.

Sources

common-mistakes.md (NHCX sandbox portal)

PreviousDummy Payer Next FAQs