Troubleshoot Carequality Interoperability Framework errors

The Carequality Interoperability Framework has disparate, varied errors. Below, we describe common errors and the steps you can take.

If you need extra support to resolve any Carequality issues, submit a ticket via our Help Desk.

HTTP error codes

If there's an issue on the Carequality side, you may see any of these errors returned after you initiate a request:

401 Unauthorized
If you receive an HTTP 401 in response to a request you send to the Framework, it's likely that your request is missing one or more Meta fields. Remember that the Meta fields are required on every step of every request to Carequality.
So if you see an HTTP 401, check your log to see if any Meta fields are missing.
403 Forbidden
[OID] already exists.
This may be returned if you attempt to create a new organization or patient record with an existing OID.
403 Forbidden
Failed to parse request body as XML resource.
This error occurs because your request body has to contain:
(a) at least one identifier element;
(b) a valid type element;
(c) at least one contact element (for implementer only); and
(d) valid display names for any defined endpoints.
403 Forbidden
id: [ID] is not valid.
This may be returned if you attempt to update or delete an organization or patient record with an OID that doesn't currently exist.
404 Not found
The patient or document you're looking for isn't found.
If this is returned, it's possible that there was a change to the patient record. We recommend running the PatientSearch.Query with the patient’s updated demographics to get the correct network patient ID.
500 Internal Server Error
Parsing XML request error!
500 Internal Server Error
Your Organization Source contains a duplicate business!

No subscriptions error

If you receive the error below, it means that the correct ID is missing in the Meta.Destinations array:

No subscriptions. Meta.Destinations needs to contain a destination from existing subscription.

In other words, we don’t recognize a valid connection, so you need to populate the ID in Meta.Destinations to indicate where you intend to send your request. The table below lists the correct destination IDs based on the request purpose for both staging and production environments:

Request purposeStaging IDProduction ID
Query for/create/update/delete an organizationa07afe3b-d247-4415-827f-6837707e1b8b5d0fd248-6c52-4ad9-b907-ae10bf2dcc39
Search for a patient with record locator serviceadf917b5-1496-4241-87e2-ed20434b1fdb97f2dc1d-c71b-43a7-a436-9b789d44c804
Search for a patient within a specific organization1ca254a8-8d42-4593-abb4-b21399d9de576391b961-55ae-430b-a789-cf575f03fca0
Search for a clinical summary/documentec745338-8849-43ad-a7ce-4bc5bf1d8b89628cbf79-1156-4923-b9d0-285906160ed6
Save patient details and documents to your repositoryThis is specific to your org—you can find the correct ID in the Redox Access wizard.This is specific to your org—you can find the correct ID in the Redox Access wizard.

Repository URL errors

You may receive an error that states:

Repository URL and certificate are required. Review destination configuration.
This means that we couldn't find the organization specified in your request. This can happen if:
(a) The organization was deactivated. In this case, query the organization directly to see if their organization record is still active.
(b) The directory you're using is outdated. Refresh your copy of the directory to make sure it's current.
(c) The organization only initiates requests and doesn't respond to other Carequality participants. This is only for organizations that meet the exemption criteria for responding to Carequality, like EMS vendors or specialty pharmacies.
Destination requires both registry and repository URLs.
This means that the Carequality organization doesn't have the appropriate information for Redox to perform the query. This is an indication that the organization entry is invalid. You may need to refresh the organization to resolve the error; it's possible that the organization may have already updated their entry, but Redox has yet to reflect that.

No documents found

If you find a match via PatientSearch then try the ClinicalSummary.PatientQuery, you may receive an error that states:

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

This occurs when the organization doesn't have any documents available for the patient. In these cases, it's possible that patient consent is missing or that the patient is registered but hasn't had a visit yet, so there isn't any clinical data available.

If you expect documents but aren't getting any, submit a ticket via our Help Desk so that we can reach out to the relevant implementers and Carequality participants.

Timeouts and connectivity

You may receive an error that states:

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

This may occur as different systems undergo maintenance or small outages. Given that these connectivity errors are typically temporary, we recommend retrying the request. If you see persistent problems with an organization, submit a ticket via our Help Desk.

Certificate errors

We follow Carequality’s Technical Trust Policy in order to connect to the Framework. This includes provisions like which certificates to exchange to participate in the Framework. You may see any of these certificate errors:

Unable to verify the first certificate
Unable to get local issuer certificate
This means that the organization you're requesting data from incorrectly installed its certificate and security is compromised.
Or, that the certificate issuers in the sandbox (i.e., staging) environment changed, and one or more of the Carequality participants hasn't updated to this new certificate chain.
To avoid this error, we recommend using the Redox test patients and Postman examples to test with since they should always work. We keep them current and working correctly on our end so that you can just focus on testing.
Self signed certificate in certificate chain
This means that the organization you're requesting data from installed the wrong certificate.
Connectivity with Carequality depends on mutual TLS authentication to ensure security. The certificates issued by Carequality need to be refreshed and reinstalled periodically.

If you see any certificate errors, submit a ticket via our Help Desk so that we can reach out to the relevant implementers and Carequality participants.

Data on demand error state

You may get this error when sending a PatientAdmin or ClinicalSummary to your data on demand repository:

Cannot process messages for Data on Demand environment 'environment', the environment is in a 'error' state.

We work to ensure first-in, first-out (FIFO) order so that data arrives in its intended order. Receiving this error indicates that there was an error processing an incoming message. For example, this could happen if you use an invalid patient identifier type. Make sure to use a unique patient OID.

At this point, we pause future messages from filing to ensure that data is not missed or corrupted. Submit a Help Desk ticket to reset the environment.

Payload or file size

You may get an error along these lines:

Payload size of X exceeded the limit of [40MB].

Redox maintains certain file or message size limits, so if you get an error like this, the file or message you're sending is too big. Refer to Redox size limits.