Troubleshooting

• 400 invalid_request — malformed JSON, missing required header or invalid parameter. Fix the request; do not retry unchanged.
• 401 unauthorized — the key is missing, malformed, expired, revoked or inactive. Replace or rotate it; do not retry unchanged.
• 403 forbidden — the authenticated key lacks the endpoint's required scope, the client is inactive, or the key's environment does not match.
• 404 not_found — the resource is unknown or deliberately undisclosed because this client lacks its Program grant or environment access.
• 409 conflict — an idempotency key was reused with a different request, or an order can no longer make the requested transition.
• 422 unprocessable — the payload is structurally valid but the Program, item, clinical requirements or serviceability decision prevents the operation.
• 429 rate_limited — wait for Retry-After, then retry the same logical request and idempotency key.
• /v1/v1 in a URL — SOLIA_API_BASE already ends in the version; append only the resource path.
• Missing results — results are exposed only after release; unreleased versions remain pending or undisclosed.

• Signature mismatch — verify the exact raw request bytes before parsing, use the secret for this client and environment, and compare in constant time.
• Timestamp rejected — your clock is outside the allowed tolerance; synchronize it.
• Duplicate deliveries — expected (at-least-once). Deduplicate on the delivery and event identifiers.
• Gaps after an outage — read the event stream from your last persisted cursor, then re-read affected orders and results.

• Orders not arriving — confirm the selected environment, Production adapter state, connection validation and transmission history.
• Connection test passes but orders are rejected — the test proves reachability and authentication only; check the laboratory's acknowledgement payload and code mappings.
• Unmapped orderables — complete and validate Catalog mappings; Solia never guesses a laboratory code.
• Unresolved clinical policy — inspect Program requirements and governed questions. Manual review is intentional until authority is configured.
• Uncertain send — the transmission may have reached the laboratory without a conclusive response. Native paths suppress automatic resend, but HTTPS/JSON retains classified retries; an authorized operator must reconcile the original outcome with the laboratory. Do not create a replacement idempotency key or blindly resend.
• Result for the wrong order, or a correction — results must correlate to the original order and transmission; corrections arrive as new versions.
• Workspace, profile or environment mismatch — a transmission is only dispatched through a connection bound to the same workspace and environment; anything else is refused.
• Native REST, FHIR, HL7, SFTP or Edge not available — these are implemented but not enabled and require an approved installation; see Connectivity status.
• Webhook temporary failure — return 2xx quickly, inspect timeout/5xx/429 behavior and bounded Retry-After; retries are scheduled automatically.
• Webhook permanent failure or dead letter — correct the endpoint or authorization, then use supported replay rather than creating a duplicate subscription.
• Sandbox/Production confusion — verify the environment label and credential prefix; credentials, Programs, adapters and records never cross the pair.

Preserve bounded authorized non-clinical identities, current revision and unknown/refused state. Stop clinically uncertain sends; use existing authorized support/reconciliation paths and lab IT confirmation. No keys, clinical free text, fabricated contact, replacement order or blind resend belongs in an incident workaround.

• Patient held for review: an identifier arrived without a recognized assigning authority (for example an HL7 PID-3 without CX.4, or a FHIR identifier without system), was expired or unverified, or matched more than one patient. Ask the laboratory to confirm the issuer; a reviewer resolves it.
• Callback quarantined: the callback could not be authenticated, was a replay, or matched zero or several orders (for example the same kit barcode across two Programs). It changes nothing until resolved.
• Result visible to the laboratory but not to your Program: results are returned only after an authorized laboratory release; preliminary results and interpretations are not final.
• Order shows sent but not accepted: the laboratory has not returned an application acknowledgement. Do not resubmit with a new key; use the same Idempotency-Key.
• Order shows outcome unknown: the send timed out. Solia is reconciling with the laboratory; it will not be resent automatically.