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

Error CodeDescription

ERR_ACCESS_DENIED

When the JWT token sent in the HTTP authorization header

  1. has expired

  2. doesn’t belong to the sender calling the API

  3. is empty

  4. doesn't have access to the called API

  5. or if the token's role validation failed

ERR_INVALID_PAYLOAD

When the request payload parsing failed for one of the following reasons:

1. Request body is not a valid JWE token (as defined in RFC 7516) 2. Any mandatory elements of JWE token are missing 3. Any elements of the JWE token are in invalid format

ERR_INVALID_SENDER

When the sender (with the input sender code) is not present in the registry or if the sender is not active.

ERR_INVALID_RECIPIENT

When the recipient (with the input recipient code) is not present in the registry or if the recipient is not active or is not allowed to be recipient of the called API.

ERR_MANDATORY_HEADER_MISSING

When one or more mandatory header fields are missing in the protected header of the request payload.

ERR_INVALID_API_CALL_ID

When x-hcx-api_call_id header is missing or format is wrong

ERR_INVALID_CORRELATION_ID

  • When x-hcx-correlation_id header value is missing or format is wrong, or

  • When x-hcx-correlation_id header value belongs to a cycle which is marked as closed (i.e. the recipient already responded with the final response), or

  • if the API call is an asynchronous callback API or communication_request/communication API and the correlation id does not exist on the HCX gateway

ERR_INVALID_TIMESTAMP

When x-hcx-timestamp header value is beyond current system time or older than the configured duration of time.

ERR_INVALID_REDIRECT_TO

When the x-hcx-status value is "response.reedirect" and if x-hcx-redirect_to value is not set or a participant is not present in the registry with the provided value or if the participant is not active in the registry.

ERR_INVALID_STATUS

When the x-hcx-status header value is out of defined values.

ERR_INVALID_DEBUG_FLAG

When the x-hcx-debug_flag header value is out of defined values or not supported on the environment

ERR_INVALID_ERROR_DETAILS

When the x-hcx-error_details header value is in invalid format, i.e. the mandatory elements "code" and "message" are missing or any of the elements are in invalid format

ERR_INVALID_DEBUG_DETAILS

When the x-hcx-debug_details header value is in invalid format, i.e. the mandatory elements "code" and "message" are missing or any of the elements are in invalid format

ERR_RECIPIENT_NOT_AVAILABLE

When the recipient api endpoint is not reachable even after all the retry attempts

ERR_INVALID_WORKFLOW_ID

  • When the x-hcx-workflow_id value is in invalid format

  • When the workflow id sent in callback API or communication_request/communication API is not present in the HCX gateway

ERR_SERVICE_UNAVAILABLE

When HCX gateway is unable to service due to interval server or infrastructure issues like the database is unavailable, or issues with any of the internal components that prevent it from fulfilling the request.

Recipient Error Scenarios

Error CodeDescription

ERR_INVALID_ENCRYPTION

The encryption of JWE token is invalid and the recipient is unable to decrypt the Cipher text in the JWE token.

ERR_INVALID_PAYLOAD

When the request payload parsing failed for one of the following reasons:

1. Request body is not a valid JWE token (as defined in RFC 7516) 2. Any mandatory elements of JWE token are missing 3. Any elements of the JWE token are in invalid format

ERR_WRONG_DOMAIN_PAYLOAD

Incorrect eObject is sent as the domain payload (e.g. Claim eObject is sent in CoverageEligibilityCheck API)

ERR_INVALID_DOMAIN_PAYLOAD

Domain payload (eObject) does not adhere to the HCX FHIR specifications (e.g.: mandatory elements are missing, invalid cardinality, etc)

ERR_SENDER_NOT_SUPPORTED

Sender is not allowed to send this API request to this recipient.

HCX Protocol errors

Recipient has to perform the following checks that are done by the HCX gateway:

  • ERR_MANDATORY_HEADER_MISSING

  • ERR_INVALID_API_CALL_ID

  • ERR_INVALID_CORRELATION_ID: check only for the format correctness

  • ERR_INVALID_TIMESTAMP

  • ERR_INVALID_REDIRECT_TO

  • ERR_INVALID_STATUS

  • ERR_INVALID_DEBUG_FLAG

  • ERR_INVALID_ERROR_DETAILS

  • ERR_INVALID_DEBUG_DETAILS

  • ERR_INVALID_WORKFLOW_ID: check only for the format correctness

ERR_SERVICE_UNAVAILABLE

When the recipient is unable to service due to interval server or infrastructure issues like the database is unavailable, or issues with any of the internal components that prevent it from fulfilling the request.

ERR_DOMAIN_PROCESSING

When the business processing of the request results in an error. The responder is expected to send back the corresponding domain response object with details of the error (using {response_r_esource}.outcome and {response__resource}.error.

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