Troubleshooting Labs

Nearly all lab order and result failures appear at one of three points: validation, routing, or result retrieval. You can identify the point of failure from the error response, selected lab's compendium, and behavior of the called endpoint.

Finding Your Issue

Find the symptom that best describes your issue, and select its linked section to read more.

Authentication and Authorization Failures

Symptom: The request is refused before the order reaches validation, so no OperationOutcome about the order's content is returned.

Common causes: The credential or its scopes are at fault rather than the order. For example:

• A missing, expired, or otherwise invalid access token, refused with a 401 whose OperationOutcome reads "Missing or invalid Authorization header value."
• A token lacking the clinical scope for the resource requested, refused with a 403 whose OperationOutcome reads "Insufficient access rights to perform the operation."

Resolution: Separate a credential problem from a scope problem, then check the scopes.

• Read the status code first. A 401 means the token wasn't accepted at all, and a 403 means it was accepted but doesn't carry the necessary rights.
• On a 403, read the WWW-Authenticate response header. An OAuth 2.0 request carries error="insufficient_scope" there.
• Compare the token's granted scopes against the resource you called. The missing scope isn't named in the response.
• Request a fresh access token and retry where the token has expired.

For obtaining and refreshing a token, go to OAuth 2.0 Authentication. For status codes and response shapes, go to Error Handling and HTTP Status Codes.

Order Submission Failures

Symptom: Order submission is rejected, with an OperationOutcome in the response.

Common causes: The order is structurally incomplete. For example:

• Missing required fields
• Incorrect or incomplete references to the patient, practitioner, or organization

Resolution: Read what is named in the rejection, then complete the order or go to the section for that class of problem.

• Read the OperationOutcome details for the specific field or reference named.
• Include all required fields and references, then resubmit.
• Where a test code is named in the message, go to Compendium Misalignment.
• Where a specimen is named in the message, go to Specimen Issues.
• Where a required question or response is named in the message, go to Required AOE Input Issues.

Example rejection:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Missing required field: performer"
    }
  ]
}

The diagnostics text varies with the field that failed.

Compendium Misalignment

Symptom: An order is rejected although it appears correct.

Common causes: The order and the selected lab's compendium hold different definitions of the same test. For example:

• Invalid or unsupported test codes
• Internal test codes used in place of lab-specific codes
• Outdated compendium mappings
• Tests unavailable at the selected lab
• Required inputs absent for specific tests

Resolution: Realign the order with the compendium.

• Map every test code to the selected lab's compendium.
• Update mappings to match current compendium definitions.
• Confirm that the selected lab offers the requested tests.
• Provide every input the compendium defines as required.

For how a compendium is structured and retrieved, go to Lab Compendium.

Order Routing and Splitting Issues

Symptom: An order is rejected, delayed, or split into several orders.

Common causes: No single lab can fulfill every test in the order. For example:

• Tests in one order belonging to different labs
• Tests unsupported at the selected lab
• Routing configuration constraints

Resolution: Align the order with what one lab can fulfill.

• Confirm that every test in an order can be fulfilled by the same lab.
• Split an order yourself when its tests belong to different labs.
• Expect Lab Network to split an order where necessary.

After a split: A split order is tracked as several orders rather than one.

• One submitted order can result in several RequestGroup resources.
• Each resulting order is tracked and managed independently.
• Confirm routing behavior for your configuration.

Specimen Issues

Symptom: An order is rejected at validation, or isn't processed.

Common causes: The specimen data is incomplete or wrong for the test. For example:

• Specimen data required for a test but not provided
• Incorrect specimen type
• Incomplete collection details

Resolution: Supply the specimen detail the compendium defines.

• Include a Specimen resource where one is required.
• Match the specimen type to the compendium requirement.
• Provide every required collection detail.

Required AOE Input Issues

Symptom: An order is rejected for missing or incorrect required inputs.

Common causes: AOE responses are absent or malformed. For example:

• Required AOE responses omitted
• Incorrect answer format, for example free text where a coded value is required
• No QuestionnaireResponse reference in ServiceRequest.supportingInfo

Resolution: Retrieve the questions, then supply typed responses.

• Retrieve the required AOE questions for the selected test.
• Provide each response in the correct data type: coding, boolean, date, and so on.
• Include the QuestionnaireResponse and reference it from ServiceRequest.supportingInfo.

Result Retrieval Issues

Symptom: No results are returned after order submission.

Common causes: The results aren't ready, or the query is wrong. For example:

• Results not yet released by the lab
• Incorrect query parameters
• Wrong resource or search criteria

Resolution: Confirm timing first, then the query.

• Allow for lab processing. Results are delivered after it completes, not at submission.
• Retrieve the report with DiagnosticReport?based-on={order-id}, adding _include=DiagnosticReport:result to return its discrete values in the same bundle.
• On this search parameter a resource-type prefix isn't required, because the order identifier alone is the search value. A resource-type prefix can still be required on other reference searches in the API.
• Reach discrete values through the report's result references, or search Observation by patient. The Health Gorilla FHIR server doesn't index based-on as a search parameter on Observation, although the element itself can carry a value.

Result Status and Corrections

Symptom: A result was retrieved earlier, and the values held may no longer be the current ones.

Common causes: A report can be replaced after it's first delivered. For example:

• A preliminary report treated as settled
• A corrected report issued after an earlier one was already stored and acted on
• Subscription criteria matching only final, so a later correction never arrives

Resolution: Read the status, then decide how a later change will reach you.

• Read DiagnosticReport.status before acting on a value. Health Gorilla reports preliminary, final, corrected, cancelled, and unknown.
• Treat preliminary as provisional. Where a later final or corrected report is expected, don't act on a preliminary value as settled.
• Treat corrected as carrying revised values for the same order, and re-read the report rather than trusting an earlier copy.
• Re-query rather than relying on a stored copy, or subscribe to DiagnosticReport so a later report reaches your system.
• Where you subscribe, confirm that corrected is included in the criteria and not only final. With criteria limited to final, a correction never arrives. Where no notification arrives at all, go to Subscription Issues.

Canceling a Submitted Order

Symptom: An order was submitted in error, or a test on it is no longer wanted.

Common causes: The order has already passed the point where it can be withdrawn. For example:

• A specimen already collected
• An order already revoked

Resolution: Revoke the order, and expect a refusal once it's too late.

• Send a PATCH to RequestGroup/{id} with a JSON Patch that replaces /status with revoked.
• Expect a refusal where the specimen has already been collected, or where the order is already revoked.

Results on an Unexpected Patient

Symptom: A result arrives under a patient record you don't recognize, or an expected result never appears on a known patient, while the ordering provider is correct.

Common causes: Lab Network resolves the provider and the patient separately and resolves the patient last, so a result can reach the right provider without reaching the right patient. For example:

• Demographics with no match to an existing record, so a new patient record was created and the result filed under it
• A result that would create a new patient record carrying none of postal code, phone number, or Social Security number, which leaves the demographic search unable to run
• More than one record already held for the same person in your organization, with the result filed under a different one
• Incomplete demographics, leaving the result in the Unassigned Queue and undelivered

Resolution: Reconcile what arrived, then reduce recurrence.

• Reconcile incoming results on their demographic fields rather than assuming your system already knows the patient identifier.
• Merge duplicate patient records in practice settings, available to the admin role, or with the Patient/$merge operation.
• Review the Unassigned Queue in the Health Gorilla web app for results that were never delivered.
• Include a consistent patient identifier, a complete date of birth, a full legal given name, and at least one of postal code, phone number, or Social Security number on inbound results.

For the full sequence and every outcome, refer to Result Routing and Matching.

Document Retrieval Issues

Symptom: Document-based results or files are missing.

Common causes: The lab sends no documents, or the query is wrong. For example:

• Labs that provide no document-based results
• Incorrect patient or category filter
• A missing Binary retrieval step

Resolution: Query for the document, then retrieve its content.

• Query DocumentReference with the correct patient and category.
• Retrieve the file content through the associated Binary resource.
• Confirm with the lab whether it provides document artifacts.

Subscription Issues

Symptom: No notifications arrive.

Common causes: The subscription is inactive, its endpoint is unreachable, or its criteria are too narrow for the data. For example:

• A Subscription resource that was never created or isn't active
• Incorrect endpoint configuration
• Event criteria too narrow for the returned data

Resolution: Check the subscription, then the endpoint, then the criteria.

• Verify that the Subscription resource is active.
• Confirm that your endpoint is reachable and accepts requests.
• Validate the subscription criteria.
• Confirm that results satisfy the criteria, for example status=final.