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 Code	Description
ERR_ACCESS_DENIED	When the JWT token sent in the HTTP authorization header has expired doesn’t belong to the sender calling the API is empty doesn't have access to the called API 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 Code	Description
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_resource}.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. __