Carequality Errors


As a distributed network made up of 28 vendors and over 18,000 healthcare facilities, Carequality has disparate and varied errors. The bulk of these will require coordination with Redox support and the support team of the queried organization. This page outlines the most common actionable errors, their meaning, and what steps you can take on your own.

Errors as Query Initiator

Invalid Queried Organization

A common error you may see is:

Repository URL and certificate are required. Review destination configuration.

This error means Redox was not able to resolve an endpoint for the organization that was queried.

  • This commonly occurs if you are using an out-of-date copy of the directory and an organization is deactivated.
  • You can troubleshoot by refreshing your copy of the directory or by querying to see that the entry is still active.
  • This may also occur if you are querying an entry that is “Query Initiator Only”, such as an EMS vendor or specialty pharmacy.

Missing Required Metadata

Another style of error you may see relates to including all required Metadata. Here’s an example:

XDSMissingHomeCommunityId: A value for the homeCommunityId is required and has not been specified

This error means you did not include a required attribute. Make sure to include the follow attributes:

  • Meta.Extensions.organization-name
  • Meta.Extensions.sender-organization-id
  • Meta.Extensions.user-id
  • Meta.Extensions.user-role
  • Meta.Extensions.purpose-of-use

See the Metadata section here for more detail on what these attributes mean and how to populate them

No Documents Found

When querying organizations, you may find a match on the patient search, but then receive the following error on ClinicalSummary.PatientQuery:

Something Went Wrong Retrieving The Document List. Error: Could Not Find Any Documents.

This occurs when the organization you’ve queried has no documents available for the patient. This could be due to missing patient consent or just lack of clinical data (i.e. the patient is registered but has not had a visit yet).

If there are scenarios where we’d expect documents but are getting none, reach out to Redox support so we can reach out to the involved Implementers and Carequality Connections.

Timeouts and Connectivity

As different systems undergo maintenance or small outages, you may see intermittent connectivity issues. Such errors include:

Request received a response with status code 504.
Socket hang up
Client network socket disconnected before secure TLS connection was established

Given that these connectivity errors are typically temporal, we recommend retrying the query. If you see persistent problems with an organization, please reach out to support.

Certificate Errors

Connectivity with the Carequality network is dependent on mutual TLS authentication to ensure security. The certificates issued by Carequality periodically need to be refreshed and re-installed. If you see the following errors, please reach out to Redox support so we can work with the queried organization on resolution

Unable to verify the first certificate

This means the queried organization installed its certificate incorrectly in a way that compromises security.

Unable to get local issuer certificate

This means the queried organization installed its certificate incorrectly in a way that compromises security.

Self signed certificate in certificate chain

This means the queried organization installed the wrong certificate.

Errors as Query Responder

If you are responding to incoming queries, you can convey back granular errors by responding with the following format:

"body": {
    "XDSErrors": [
	    "code": "XDSUnknownPatientId",
	    "message": "Patient Not Found."

body.XDSErrors.code should be one of the following:

  • XDSRepositoryOutOfResources
  • XDSRepositoryBusy
  • XDSRepositoryError
  • XDSUnknownPatientId

body.XDSErrors.message may be any additional information you wish to convey back to the sender about your error.