NHCX Delivery Failures

Overview

Every request the hospital sends to NHCX — a pre-authorization, a claim, a coverage check — is delivered by the exchange (the gateway) to the payer. When the gateway cannot deliver a request it retries a few times, then gives up and tells us so through the error endpoint. That report is how a request that never reached the payer is distinguished from one still waiting for the payer's decision.

Without it, both look the same: a case that simply sits there. With it, the failure is recorded on the case, matched to it by the correlation ID the report quotes.

What you see

When a delivery report arrives for a case:

• A new ERROR_ON_REQUEST step is added to the same workflow, carrying the gateway's report in full. That step is what shows the case as failed.
• Click the red ⚠ next to the ERROR_ON_REQUEST step to read the report — the error code, the message, and the trace.
• The request you sent is left exactly as it was: it keeps "request sent" and its id still opens the FHIR that was sent. The report never overwrites what was sent.

Nothing is retried automatically. The original correlation ID is retired once the gateway gives up, so a resubmission must start a new request (a new correlation ID) — send the pre-authorization or claim again from the case as you normally would.

Common Issues

• A step is red but the report says nothing useful — the ⚠ popup belongs to the ERROR_ON_REQUEST step, not to the request row. Open the popup on the ERROR_ON_REQUEST row to see the gateway's code and message.
• The request row still opens a document — that is intended. The report records the failure beside the request, it does not change it, so the sent FHIR remains printable for reference.
• No step appears after a request seems to hang — the report arrives only after the gateway has exhausted its delivery attempts, which can take a while. If the payer later answers, that response appears normally.
• A case shows a delivery failure but the payer says it received the request — the payer may have received it after a retry the gateway counted as failed. Confirm with the payer before resubmitting, so the case is not submitted twice.

FAQ

Q: What is the error endpoint? A: It is a route every NHCX participant must host so the gateway can report a delivery it could not complete. We host it; the gateway posts to it. It is not something you call.

Q: Do I need to do anything when I see a delivery failure? A: Yes — the request did not reach the payer. Read the report, confirm the cause, and resubmit from the case. A resubmission is a new request with a new correlation ID.

Q: Can I reuse the same correlation ID? A: No. The correlation ID is retired when the gateway gives up. Resubmitting from the UI starts a fresh request.

Q: Will the request still appear in the case timeline? A: Yes. It stays in the workflow exactly as it was sent, with its FHIR still printable, and the ERROR_ON_REQUEST step sits beside it with the gateway's account of the failure.