API Response Handling

Return the correct NHCX protocol response after each request and error scenario.

Each recipient must acknowledge each NHCX request with HTTP 202 Accepted. This response closes the delivery attempt at the NHCX gateway. If a recipient rejects a payload, it must send a protocol error response.

Retry behavior

If the recipient misses the required response, NHCX retries the delivery 5 times. After 5 failed attempts, NHCX deletes the request for that correlation ID.

Acceptance response

Return HTTP 202 Accepted when the recipient accepts the request for further action. Use this shape for the response body.

Accepted response body

{
  "timestamp": "DD/MM/YYYY hh:mm:ss.SSS",
  "api_call_id": "UUID",
  "correlation_id": "UUID",
  "result": {
    "sender_code": "PYRXX@hcx",
    "recipient_code": "INXXXXX@hcx",
    "entity_type": "coverageeligibility",
    "protocol_status": "request.queued"
  },
  "error": {
    "code": "",
    "message": ""
  }
}

Acceptance fields

Field	Value
`timestamp`	The response timestamp.
`api_call_id`	The API call UUID from the request.
`correlation_id`	The request cycle UUID.
`sender_code`	The sender participant code.
`recipient_code`	The recipient participant code.
`entity_type`	`coverageeligibility`, `preauth`, `claim`, `task`, `payment`, or `insuranceplan`.
`protocol_status`	`request.queued`, `request.dispatched`, or `request.error`.
`error.code`	Empty for acceptance.
`error.message`	Empty for acceptance.

Error response

Send a ProtocolResponse when the recipient rejects the payload after evaluation. Set x-hcx-status to response.error. Include an error code, a message, and a trace when available.

Protocol error response

{
  "type": "ProtocolResponse",
  "x-hcx-sender_code": "",
  "x-hcx-recipient_code": "",
  "x-hcx-api_call_id": "UUID",
  "x-hcx-correlation_id": "UUID",
  "x-hcx-workflow_id": "UUID",
  "x-hcx-timestamp": "",
  "x-hcx-debug_flag": "Error",
  "x-hcx-status": "response.error",
  "x-hcx-redirect_to": "",
  "x-hcx-error_details": {
    "code": "String",
    "message": "String",
    "trace": "String"
  },
  "x-hcx-debug_details": {
    "code": "String",
    "message": "String",
    "trace": "String"
  },
  "x-hcx-domain-header": {
    "use_case_name": "String",
    "amt_processed": "String"
  },
  "x-hcx-entity-type": "coverageeligibility",
  "x-hcx-ben-abha-id": "ABHA_NUMBER"
}

Error fields

Field	Value
`type`	`ProtocolResponse`.
`x-hcx-sender_code`	The sender participant code.
`x-hcx-recipient_code`	The recipient participant code.
`x-hcx-api_call_id`	The API call UUID.
`x-hcx-correlation_id`	The request cycle UUID.
`x-hcx-workflow_id`	The workflow ID.
`x-hcx-debug_flag`	`Error` for an error case.
`x-hcx-status`	`response.error`.
`x-hcx-error_details`	The error code, message, and trace.
`x-hcx-debug_details`	The debug code, message, and trace.
`x-hcx-entity-type`	`coverageeligibility`, `payment`, `insuranceplan`, `task`, `claim`, or `preauth`.
`x-hcx-ben-abha-id`	The beneficiary ABHA number, when available.

Required implementation

Return acceptance first

Return HTTP 202 Accepted for each valid NHCX request. Include the acceptance response body.

Validate the payload

Validate the decrypted payload and protected header. Use the same correlation ID for the request cycle.

Send a protocol error

Send the ProtocolResponse when the payload fails validation. Set x-hcx-status to response.error.

Implement the error callback

Implement the /v1/error API at your endpoint. Use it to receive failure details from NHCX.

Failure outcomes

Scenario	NHCX result	Correct action
The recipient returns no HTTP `202`.	NHCX retries the request.	Return HTTP `202 Accepted`.
The response body has the wrong shape.	NHCX treats the attempt as an error.	Use the acceptance response body.
The recipient rejects the payload.	NHCX needs a protocol error response.	Send a `ProtocolResponse` with `response.error`.
A server error prevents delivery.	The sender receives the failure details.	Implement `/v1/error`.

Sources

api-response-handling.md (NHCX sandbox portal)

PreviousStandard Error Codes Next API Specifications