Appendix A: Common errors

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

If you need extra support to resolve any Carequality issues, contact our Help Desk.

When initiating requests

403 Forbidden[OID] already exists.
403 ForbiddenFailed 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 Forbiddenid:[ID] is not valid.For update or delete messages only.
404 Not found.The file you're looking for isn't found.
500 Internal Server ErrorParsing XML request error!
500 Internal Server ErrorYour Organization Source contains a duplicate business!

Destination error

You may receive an error that states:

This means that the endpoint you specified to receive the request is invalid. The ID for the receiving endpoint should be in the Meta.Destinations array of your request. The ID differs based on the environment and the type of request.

How to resolve

If you receive this error, refer to the table below to make sure that you entered the correct ID.

Request purposeStaging IDProduction ID
Query for/create/update/delete an organizationa07afe3b-d247-4415-827f-6837707e1b8b5d0fd248-6c52-4ad9-b907-ae10bf2dcc39
Search for a patient within the entire Frameworkadf917b5-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 digital record retrieval wizard.This is specific to your org—you can find the correct ID in the digital record retrieval wizard.

Inactive organization

You may receive an error that states:

Inactive Organization Error

Repository URL and certificate are required. Review destination configuration.

This means that we we couldn't find the organization specified in your request. This can happen if:

  • The organization was deactivated,
  • The directory you're using is outdated, or
  • The organization is a Query Initiator only.

The last possibility may be the case for organizations like EMS vendors or specialty pharmacies.

How to resolve

  1. Refresh your copy of the directory to make sure it's the most current.
  2. Query the organization directly to see if the entry is still active.

No documents found

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

No document found error

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.

How to resolve

If you expect documents but aren't getting any, contact 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:

Timeout error

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.

How to resolve

Given that these connectivity errors are typically temporary, we recommend retrying the request. If you see persistent problems with an organization, contact our Help Desk.

Certificate errors

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.

You may also see:

Self signed certificate in certificate chain

This means that the organization you're requesting data from installed the wrong certificate.

Connectivity with the Carequality Interoperability Framework depends on mutual TLS authentication to ensure security. The certificates issued by Carequality need to be refreshed and reinstalled periodically.

How to resolve

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

When processing requests

If you're responding to incoming requests, you can return granular errors by responding with the following format:

In the body.XDSErrors.code field, you can return any of the following errors :

  • XDSRepositoryOutOfResources
  • XDSRepositoryBusy
  • XDSRepositoryError
  • XDSUnknownPatientId

In the body.XDSErrors.message field, you can include any additional information you want to relay back to the sender about the error.