Troubleshoot Carequality Interoperability Framework errors

Last updated: Nov 14, 2024

SUPPORT

IMPLEMENTATION

HEALTH TECH VENDOR

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.

Code	Error message	Notes
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	Notes
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 purpose	Development ID	Production ID
Perform a broad patient search	`adf917b5-1496-4241-87e2-ed20434b1fdb`	`97f2dc1d-c71b-43a7-a436-9b789d44c804`
Perform a patient search within a specific organization	`1ca254a8-8d42-4593-abb4-b21399d9de57`	`6391b961-55ae-430b-a789-cf575f03fca0`
Query for/create/update/delete an organization	`a07afe3b-d247-4415-827f-6837707e1b8b`	`5d0fd248-6c52-4ad9-b907-ae10bf2dcc39`
Search for a clinical summary/document	`ec745338-8849-43ad-a7ce-4bc5bf1d8b89`	`628cbf79-1156-4923-b9d0-285906160ed6`
Save patient details and documents to your repository	This 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	Notes
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.

Error message

Notes

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	Notes
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.

Error message

Notes

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	Notes
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.

Error message

Notes

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	Notes
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	Notes
Unable to verify the first certificate or 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.

Error message

Notes

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	Notes
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.

Error message

Notes

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	Notes
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.

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.