Errors

Every refusal is JSON { "error": "<code>", "message": "<text>" }. Branch on error; handle a code you do not know by its category. message is safe to log and never carries patient data.

Category	Meaning	Do
`invalid_request`	the request is malformed or breaks a rule	fix it; resubmit with a new Idempotency-Key
`access`	the key, signature, scope, grant or environment does not allow it	fix the credential or ask for the scope or grant
`refused`	a well-formed request a business or compliance rule refuses	nothing was executed; change what the code names
`not_found`	no such resource for this credential	check the id and the clinic
`conflict`	the state moved (a price, a quote, another request)	follow the code: re-quote or read by id
`retryable`	rate limited, in flight, or a TrueRoute fault	retry the SAME key and bytes after a pause

What a module POST outcome means

Outcome	Executed	Do
2xx	yes	Store the body. A replay of the same key returns the same body.
4xx access / invalid_request / refused / not_found	no	Fix the request; resubmit with a NEW Idempotency-Key.
409 request_in_flight	no (not yet)	Retry the SAME key and bytes.
409 other conflict codes	no	Follow the code: re-quote, or read the resource by id or externalOrderId.
429, 5xx, timeout, unparseable 2xx	unknown	Treat as ambiguous. Retry the SAME key and bytes, or read by externalOrderId to reconcile.

Order contract codes

Code	Category
`artifact_hash_mismatch`	`invalid_request`
`artifact_too_large`	`invalid_request`
`authentication_failed`	`access`
`billing_mode_unresolved`	`refused`
`bundle_band_not_approved`	`refused`
`bundle_component_vendor_id_missing`	`refused`
`bundle_not_resolved`	`refused`
`bundle_package_not_ready`	`refused`
`bundle_package_underfilled`	`refused`
`clinic_price_missing`	`refused`
`clinical_release_conflict`	`conflict`
`clinical_release_not_permitted`	`refused`
`clinical_release_required`	`invalid_request`
`clinical_release_window_expired`	`refused`
`controlled_substance_out_of_scope`	`refused`
`dose_not_on_ladder`	`invalid_request`
`environment_mismatch`	`access`
`external_order_id_conflict`	`conflict`
`funding_amount_mismatch`	`invalid_request`
`funding_collection_conflict`	`conflict`
`funding_collection_exhausted`	`refused`
`funding_evidence_mismatch`	`invalid_request`
`funding_evidence_not_permitted`	`invalid_request`
`funding_evidence_required`	`invalid_request`
`funding_not_affirmed`	`invalid_request`
`funding_not_collected`	`refused`
`funding_reversal_after_dispatch`	`refused`
`funding_split_does_not_balance`	`invalid_request`
`funding_timestamp_implausible`	`invalid_request`
`gate_rejected`	`refused`
`idempotency_key_required`	`invalid_request`
`idempotency_key_reuse`	`invalid_request`
`insufficient_scope`	`access`
`integration_suspended`	`access`
`internal_error`	`retryable`
`invalid_days_supply`	`invalid_request`
`missing_field`	`invalid_request`
`multiple_prescriptions_not_supported`	`invalid_request`
`npi_mismatch`	`invalid_request`
`npi_verification_synthetic_not_live`	`refused`
`office_use_not_supported`	`invalid_request`
`order_already_funded`	`conflict`
`order_not_found`	`not_found`
`order_not_releasable`	`refused`
`passthrough_quote_not_permitted`	`refused`
`pharmacy_not_offered`	`refused`
`prescriber_clinic_not_granted`	`access`
`prescriber_grant_scope_missing`	`access`
`prescriber_identity_collision`	`conflict`
`prescriber_not_found`	`not_found`
`price_changed`	`conflict`
`pricing_not_configured`	`refused`
`product_not_available`	`refused`
`product_not_found`	`not_found`
`provider_inactive`	`refused`
`provider_not_on_file`	`refused`
`quantity_required`	`invalid_request`
`quantity_unit_mismatch`	`invalid_request`
`quote_expired`	`conflict`
`quote_input_mismatch`	`invalid_request`
`quote_not_found`	`not_found`
`rate_limited`	`retryable`
`regimen_line_mismatch`	`invalid_request`
`regimen_not_permitted`	`invalid_request`
`regimen_required`	`invalid_request`
`regimen_shipping_service_not_offered`	`refused`
`release_artifact_mismatch`	`invalid_request`
`release_not_affirmed`	`invalid_request`
`release_precedes_signature`	`invalid_request`
`release_timestamp_implausible`	`invalid_request`
`request_in_flight`	`retryable`
`script_artifact_too_large`	`refused`
`signature_expired`	`access`
`signature_required`	`access`
`signature_timestamp_implausible`	`invalid_request`
`structured_match_not_affirmed`	`invalid_request`
`text_too_long`	`invalid_request`
`timestamp_out_of_window`	`access`
`transport_cannot_carry_order`	`refused`
`unauthorized`	`access`
`unknown_field`	`invalid_request`
`unsupported_field`	`invalid_request`
`unsupported_funding_method`	`invalid_request`
`unsupported_media_type`	`invalid_request`
`unsupported_release_method`	`invalid_request`
`upstream_signing_not_enabled`	`access`

Module codes

Module routes also answer the shared codes above where they apply, with these statuses.

Code	Status	Category	Meaning
`aoe_answer_missing`	400	`invalid_request`	A required ask-at-order-entry question from the catalog has no answer.
`appointment_not_found`	404	`not_found`	No such appointment for this clinic.
`appointment_not_modifiable`	422	`refused`	The appointment is in a state that cannot be rescheduled or cancelled (completed, cancelled, inside the vendor cutoff).
`appointment_slot_unavailable`	422	`refused`	The slot is no longer available. List slots again.
`authority_mode_mismatch`	400	`invalid_request`	The order's declared clinicalAuthorityMode is not the clinic's recorded arrangement. The mode is declared so the caller knows who is responsible; it is never chosen by the body.
`authority_mode_not_enabled`	422	`refused`	The trueeval_supplied authority mode has no recorded activation for this clinic and state.
`authority_mode_state_restricted`	422	`refused`	The clinic's clinical authority mode may not order for a patient in this state until counsel rules (the trueeval_supplied mode is held for New York, New Jersey, Rhode Island and Maryland).
`billing_arrangement_missing`	422	`refused`	No billing arrangement is recorded for this (integration or grant, module). Who pays is never taken from the request.
`cancel_target_ambiguous`	400	`invalid_request`	A cancel names neither or both of journeyId and externalOrderId. Name exactly one.
`card_on_file_required`	422	`refused`	The arrangement makes the clinic the payer under standard_billed and the clinic has no valid card on file, or ordering is paused for an uncollected recovery (TR-471). Never answered under passthrough.
`clinic_id_required`	400	`invalid_request`	Every module request names clinicId: in the signed body of a POST, in the query of a GET.
`clinic_mapping_pending`	403	`refused`	The clinic mapping was requested and is awaiting (or was refused) TrueRoute operator approval.
`clinic_not_leaf`	403	`access`	The named clinicId is a brand or parent organization. Module requests act for one clinic only.
`clinic_suspended_by_consumer`	403	`refused`	The consumer's own lock for this clinic is suspended or archived. New orders are refused; results and critical facts for existing orders continue.
`clinician_assertion_not_enabled`	403	`refused`	This integration's counsel gate for registering clinicians is OFF (the default). Clinicians are registered in the console instead.
`clinician_licence_state`	422	`refused`	The clinician holds no in-date licence (with a recorded expiry) for the patient's state.
`clinician_not_authorized`	422	`refused`	The clinician is not active at this clinic, not linked to this integration or grant, or not permitted under the authority mode.
`clinician_not_found`	404	`not_found`	No clinician with this id is registered to the clinic.
`clinician_npi_conflict`	409	`conflict`	The NPI is already registered at this clinic under a different externalClinicianId.
`clinician_selection_required`	422	`refused`	clinicianId was omitted and the server cannot derive exactly one eligible clinician. Name one from GET /v1/modules/clinicians.
`collection_device_not_found`	404	`not_found`	No such collection device in the catalog.
`collection_device_required`	400	`invalid_request`	The device_kit rail needs a collectionDevice (device and setting); other rails must send null.
`collection_rail_not_offered_for_lab`	400	`invalid_request`	The collection rail cannot carry a specimen for this lab, or for one of the tests named.
`connect_session_not_found`	404	`not_found`	No such connect session, or it expired.
`connection_already_active`	409	`conflict`	The patient already has an active connection for this source. Disconnect it first.
`critical_ack_clinician_invalid`	400	`invalid_request`	An acknowledgement names at most one of clinicianId / externalClinicianId, and a clinical follow-up names exactly one (the clinician who made it). Only `escalated_to_responsible_clinician` may name neither.
`critical_ack_not_permitted`	403	`refused`	This acknowledgement may not be recorded over the API: the clinic is under trueeval_supplied authority on an integration not flagged trueEvalOwnedConsumer; or the action is `escalated_to_responsible_clinician` and the escalation owner is not `consumer`; or the named clinician is not a result reader at this clinic; or the fact is on an UNMATCHED result (not yet bound to an order), which reads owner `trueroute` because TrueRoute is finding the ordering clinician, and is not acknowledged over the API until it is bound.
`critical_already_acknowledged`	409	`conflict`	The statement conflicts with one already recorded: a second `escalated_to_responsible_clinician`, a receipt after a clinical follow-up, or a second, different clinical follow-up. A replay with the same Idempotency-Key is not this code. Read the fact.
`critical_contact_missing`	422	`refused`	The ordering clinician has no 24/7 critical-value contact on record (CLIA 42 CFR 493.1291(g)). No diagnostic order is placed for a clinician the performing lab could not reach.
`critical_escalation_owner_missing`	422	`refused`	No critical escalation owner is recorded for this clinic. No diagnostic order is placed without one.
`critical_escalation_owner_not_permitted`	422	`refused`	The clinic is under trueeval_supplied authority with escalation owner `consumer`, which only an integration a TrueRoute operator has flagged trueEvalOwnedConsumer may run. Every other integration's trueeval_supplied clinics need owner `trueroute`.
`critical_fact_not_found`	404	`not_found`	No such critical fact for this clinic.
`device_connection_not_found`	404	`not_found`	No such device connection for this clinic.
`device_setting_not_permitted`	422	`refused`	The collection device's cleared settings do not include the requested setting (e.g. an in-clinic-only device ordered at_home).
`device_source_not_supported`	422	`refused`	The device source is not offered on this rail now.
`diagnosis_code_invalid`	400	`invalid_request`	A diagnosis code is not a valid, billable ICD-10-CM code in effect on the order date.
`document_not_found`	404	`not_found`	No document is stored for this version or requisition.
`external_org_id_conflict`	409	`conflict`	A mapping for this externalOrgId already exists for this integration and environment.
`grant_missing`	403	`access`	The named clinicId is neither this integration's clinic nor a leaf clinic it holds an active, in-window grant for (or the grant lacks this scope).
`invalid_brand`	400	`invalid_request`	described in the modules handoff provided with your credentials
`invalid_demographics`	400	`invalid_request`	A demographics field is missing or malformed (date, state, postal code, E.164 phone).
`invalid_identifier`	400	`invalid_request`	An id is not a well-formed TrueRoute id, or an external id is empty, too long or not printable.
`invalid_time_window`	400	`invalid_request`	A from/to window is reversed, open on both ends, or longer than the route allows.
`invoice_not_found`	404	`not_found`	No such invoice record for this clinic.
`journey_not_found`	404	`not_found`	No such journey (or externalOrderId) for this clinic.
`kit_shipment_not_found`	404	`not_found`	No such kit shipment for this clinic.
`lab_bill_type_not_permitted`	422	`refused`	The performing lab may not bill the clinic arrangement's bill type (client, patient or third_party) for a patient in this state under the current lab compliance policy, or the policy has no rule for that state and bill type (an unknown state and bill type is refused). E.g. New York and New Jersey: patient or insurer billing only.
`lab_billing_conditions_unmet`	422	`refused`	The patient's state allows this bill type only with conditions the clinic arrangement does not record: pass-through pricing with no markup, and the performing lab disclosed to the patient (e.g. California client billing).
`module_not_enabled`	403	`refused`	The clinic does not hold this module. Toggled per clinic by an operator; default OFF.
`module_suspended`	403	`refused`	The module or rail is suspended. New orders are refused; results, corrections, critical escalation, reads, cancellations and refunds continue.
`order_closed`	422	`refused`	The lab order is closed (cancelled, refused by the lab, resulted, or its specimen is with the lab): no collection visit can be booked or moved for it.
`order_not_cancellable`	422	`refused`	The lab order has passed the point of cancellation (specimen received, or already resulted or cancelled).
`patient_contact_missing`	422	`refused`	A mobile draw needs the patient's email address and a 10-digit US phone number, and the patient reference lacks one (`invalidFields`). Update the patient's demographics, then book again.
`patient_facing_brand_missing`	422	`refused`	The clinic has no patient-facing brand, and this rail has a patient-facing surface.
`patient_ref_conflict`	409	`conflict`	A reference for this externalPatientId already exists with different demographics. Never merged or overwritten; append a demographics version to the existing reference.
`patient_ref_not_found`	404	`not_found`	No patient reference with this id or externalPatientId exists for this integration, environment and clinic.
`patient_state_not_served`	422	`refused`	The lab, rail or test cannot serve the patient's state.
`payment_method_required`	422	`refused`	Under standard_billed, the derived payer has no usable payment method on file at TrueRoute. Never answered under passthrough.
`quote_not_orderable`	422	`refused`	The quote's eligibility is `ineligible` or `unknown`, or a test on it is unpriced. An unknown is never ordered or charged.
`rail_capability_unavailable`	422	`refused`	The rail does not offer this operation (see RailCapabilities): e.g. booking on a walk-in-only rail, or `priority: stat` on a rail whose `statPriority` is false.
`rail_not_enabled`	403	`refused`	The clinic holds the module but not this rail (lab, collection rail or device rail).
`readiness_not_live`	422	`refused`	The module or rail is not live for this environment (setup_required, or sandbox-only on a live key). GET /v1/modules/availability names the blockers.
`responsible_party_missing`	422	`refused`	The clinic has no declared responsible party for critical values. No diagnostic order is placed without one.
`result_not_found`	404	`not_found`	No such result for this clinic.
`result_version_not_found`	404	`not_found`	No such version of this result.
`return_url_not_registered`	400	`invalid_request`	A device connect returnUrl is not on the integration's registered return-URL allowlist.
`site_not_found`	404	`not_found`	No such collection site on this rail.
`slot_not_found`	404	`not_found`	No such slot, or it expired. List slots again.
`test_not_found`	404	`not_found`	No such test in this lab's catalog.
`test_not_orderable`	422	`refused`	A test is in the lab catalog but not orderable for this clinic now (not approved, not priced, or withdrawn).
`tests_empty`	400	`invalid_request`	A quote or order names no tests.
`vendor_unavailable`	503	`retryable`	The vendor could not be reached BEFORE anything was sent. Retry with the same Idempotency-Key and bytes. (A send whose outcome is unknown is never this code: it is an accepted request whose state is `ambiguous`.)

Errors

Categories

What a module POST outcome means

Order contract codes

Module codes