When something breaks

Find the symptom you are seeing, not the error code. Each chapter here walks the checks in order, so you can start without knowing which code applies. They run in the order a message travels: your token, your address, delivery, encryption, the bundle, then the identifiers that tie a cycle together.

• Every NHCX call returns 401: every endpoint fails the same way, not one call.
• Your callback URL is rejected or never called: the endpoint update is refused, or nothing ever reaches your server.
• Accepted with 202, and no callback arrives: the exchange took your request and nothing followed.
• The recipient cannot decrypt your message: the answer is a ProtocolResponse carrying PAYR-1001.
• The payer rejects your FHIR bundle: the answer names a bundle fault such as PAYR-1004 or PAYR-1008.
• Responses arrive against the wrong request: answers land on the wrong case, or the exchange refuses a duplicate.

If you already hold an error code, Troubleshooting in the Reference is organised the other way, by layer and by code. Error Codes lists every code either side can send.

A service name you do not recognise​

The name in a log line or a URL does not always match the exchange. Reprocess is served by taskhcxservice, notifications by subscriptionhcxservice, payment by servicehcxpayment.

Environments and addresses has the full address of each.

Next steps​

• Troubleshooting: the five layers and the symptom table.
• Get your sandbox credentials: where to write, and what to put in the message.