Error Handling

Types of protocol errors, list of error codes and their descriptions

This section provides details of handling protocol related errors, their categorisation, standard list of errors and how they need to be responded back in the asynchronous responses (specially when they are generated at the recipient end). For details on how to handle business processing related error please see Handling Processing Errors section.

Categories and List of protocol errors

HCX gateway and the participant systems (mainly, the recipient systems) need to validate for certain conditions and raise errors with appropriate error codes and details. Broadly, there are following two categories of errors:

  1. HCX Gateway Error Scenarios - Protocol header related checks that are validated by the HCX gateway and gateway processing related error scenarios. The gateway may send these error responses to the caller either synchronously in the HTTP response to the API call or in the asynchronous callback API.

  2. Recipient Error Scenarios - Error scenarios that are validated by the recipient systems. These error responses are sent in the asynchronous call back API to HCX/Original caller.

HCX Gateway Error Scenarios

Recipient Error Scenarios

Responding to Asynchronous Protocol Errors

While protocol errors detected during call from request or callback originator can be responded using ErrorResponse schema during the synchronous API response, many of these checks will happen asynchronously for the request/calback originator. E.g. when a provider submits a claims request, payor may asynchronously find out that JWE payload was invalid, or the format of the FHIR object was invalid. In such cases, protocol requires the error to be reported back as HCX protocol error using following mechanism:

  1. System (HCX or Recipient of the the call) generates the protocol header as it would for any response (with correlation_id, sender, recipient, timestamp etc.).

  2. x-hcx-status in the protocol header is set to "response.error".

  3. Error code in x-hcx-errordetails header needs to be set to one of the relevant error code as mentioned above.

  4. Instead of the JWEPayload, this protocol header object is send as part of the body of the response callback (on_request or on_submit or on_status etc.). This is achieved in OpenAPI 3.0 definition of the callback APIs using oneOf construct of OpenAPI 3.0 Specification. Here's the snippet of how the requestBody defintion of the callback APIs:

  requestBody:
    content:
      application/json:
        schema:
          oneOf:
            - $ref: '#/components/schemas/JWEPayload'
            - $ref: '#/components/schemas/ErrorHeader'

5. The recipient of the callback can identify the outcome based on the type of the schema recieved in the callback body and take necessary measures for further processing. __

Last updated