Troubleshoot Carequality Interoperability Framework errors

Last updated: Apr 30, 2024

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 Help Desk ticket.

HTTP error codes

You may see HTTP error codes returned if there's an issue on the Carequality side of the data exchange.

Error message
401 Unauthorized
If you receive an HTTP 401 in response to a request you send to Carequality, your request is probably 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.
This may occur if the patient record has changed. We recommend running 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

You may see a subscription error returned if the correct ID is missing in the Meta.Destinations array.

Error message
No subscriptions. Meta.Destinations needs to contain a destination from existing subscription.
This means 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.

Review the correct destination IDs based on the purpose of the request for both staging and production environments:

Request purposeStaging IDProduction ID
Search for a patient with Redox Accessadf917b5-1496-4241-87e2-ed20434b1fdb97f2dc1d-c71b-43a7-a436-9b789d44c804
Search for a patient within a specific organization1ca254a8-8d42-4593-abb4-b21399d9de576391b961-55ae-430b-a789-cf575f03fca0
Query for/create/update/delete an organizationa07afe3b-d247-4415-827f-6837707e1b8b5d0fd248-6c52-4ad9-b907-ae10bf2dcc39
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. Redox provides the correct ID.This is specific to your org. Redox provides the correct ID.

Request not authorized

You may see an error related to unauthorized requests. This can happen when attempting a DocumentGet to retrieve a document after a successful DocumentQuery.

Error message
XDSRepositoryError: The request is not authorized.
Check the sender-organization-id.
First, this shouldn't be populated with the Redox gateway but rather your own organization ID. Make sure to retrieve the document as yourself rather than mistakenly querying on behalf of Redox.
Second, confirm that you're using a production OID, not staging or dev.
This error may be more common with Epic sites, since Epic reserves a document ID for the querying organization plus patient combination. If anyone else tries to retrieve that document ID, Epic rejects the request as unauthorized.

Repository URL required

You may receive repository errors if there are discrepancies in organization information.

Error message
Repository URL and certificate are required. Review destination configuration.
This means that we couldn't find the organization specified in your request. This could 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 indicates 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

You may see errors returned for no patient documents, even if you've successfully found a matching patient with a previous query. For example, if you find a match via PatientSearch then try the ClinicalSummary.PatientQuery.

Error message
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 Help Desk ticket so that we can reach out to the relevant implementers and Carequality participants.

Timeouts and connectivity

You may receive timeout or connectivity errors as different systems undergo maintenance or small outages.

Error message
Request received a response with status code 504.
Likely due to a system maintenance or outage issue. Retry the request.
Socket hang up
Likely due to a system maintenance or outage issue. Retry the request.
Client network socket disconnected before secure TLS connection was established.
Likely due to a system maintenance or outage issue. Retry the request.

These connectivity errors are typically temporary. If you see persistent problems with an organization, submit a Help Desk ticket.

Certificate verification

You may see certificate errors when querying.

We follow Carequality’s Technical Trust Policy to connect to the Carequality Framework. This includes provisions like which certificates to exchange to participate in Carequality.

Error message
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 have 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 provide security. The certificates issued by Carequality need to be refreshed and reinstalled periodically.

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

Data on demand error state

You may see an error when sending a PatientAdmin or ClinicalSummary to your data on demand repository.

Error message
Cannot process messages for Data on Demand environment 'environment', the environment is in a 'error' state.
We work to deliver in 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 make sure that the data isn't missed or corrupted. Submit a Help Desk ticket to reset the environment.

Payload or file size

You may get an error related to payload or file sizes.

Error message
Payload size of X exceeded the limit of [40MB].
Redox maintains certain file or message size limits. If you get an error like this, the file or message you're sending is too big. Refer to Redox size limits.