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:
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.
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
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
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:
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.).
x-hcx-status in the protocol header is set to "response.error".
Error code in x-hcx-errordetails header needs to be set to one of the relevant error code as mentioned above.
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:
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