XDR-Based Messaging Errors
This section provides non-normative, informational guidance on how errors and faults may be reported when exchanging XDR-based messages, and how to handle each. It is intended to help interpret failure responses and design appropriate error-handling behavior, both for failures you receive and for failures your own system returns (see Error Management for guidance on producing errors). For a complete failure response, see Example 4.8-1 (Handling the Synchronous Response). Delivery-outcome failures reported asynchronously - DSN failures and delivery timeouts - are covered in Delivery Status Notification (DSN) and XDR-Based Messaging Best Practices).
Errors fall into two broad categories:
Category | When it occurs | Examples | How to handle |
|---|---|---|---|
Transport / SOAP-level fault | Before XDR processing occurs; the SOAP stack detects the fault, no XDR RegistryResponse is returned. | Authentication or authorization failures; TLS or connectivity errors; malformed or invalid SOAP envelopes. | Retry with exponential backoff for transient conditions (connectivity, timeouts); verify certificates, credentials, and endpoint. Do not retry authentication or malformed-message faults without fixing the cause. Escalate to Surescripts support if persistent. |
XDR application-level error | After the SOAP exchange completes successfully; the response contains a RegistryResponse with a Failure status and a RegistryErrorList. | Invalid or missing addressing; message validation or schema errors; sender or recipient configuration issues; transformation or packaging failures. | Review RegistryErrorList details; correct the message content, addressing, or configuration. Do not retry without fixing the root cause. Note that errorCode carries descriptive text rather than a stable code; see "What Surescripts Returns in a Failure Response" below. |
What Surescripts Returns in a Failure Response
When Surescripts rejects an XDR message, it populates the RegistryError as follows:
Attribute | What Surescripts sends |
|---|---|
errorCode | A human-readable description of the condition detected, not a standards-defined code. The text varies by condition and is not guaranteed to be stable across releases. |
codeContext | A fixed, general value such as Invalid XDR Message. |
severity | The short token Error, not the full urn:oasis:names🇹🇨ebxml-regrep:ErrorSeverityType:Error URN. |
location | May contain a non-meaningful placeholder value. Ignore it. |
Important: Because errorCode carries variable descriptive text rather than a stable identifier, do not use it for programmatic branching or automated retry decisions, and do not pattern-match against the standard IHE codes listed below. Use the RegistryResponse Failure status as the machine-readable outcome, log the complete RegistryError for diagnosis, and present the errorCode text to users or support staff. Retry decisions should be based on the failure category in the table above and on the transport conditions described in Message Submission and Retry.
Standard IHE Error Codes for Your Own Responses
Surescripts does not emit the codes below. They are the standard IHE ITI Technical Framework (Volume 3) values defined for the Provide and Register Document Set-b transaction, and they are provided here as a reference for the failure responses your system returns when it cannot accept a message (see Sending the Message Response and Error Management). Using standards-defined codes in your own responses lets your trading partners handle your failures programmatically.
errorCode | Typical meaning | Handling |
|---|---|---|
XDSRegistryError / XDSRepositoryError | A general error processing or storing the submission, used when no more specific code applies. | Review the accompanying detail; may be transient (retry with backoff) or may require correcting the message. |
XDSRegistryBusy / XDSRepositoryBusy | The service is temporarily unable to process the request. | Transient - retry with exponential backoff (Message Submission and Retry). |
XDSRegistryMetadataError | Required metadata is missing, malformed, or invalid. | Correct the metadata (Message Metadata) and resubmit; do not retry unchanged. |
XDSRegistryDuplicateUniqueIdInMessage | Two objects in the same submission share a uniqueId. | Assign distinct uniqueId values and resubmit. |
XDSDuplicateUniqueIdInRegistry | A uniqueId in the submission already exists on the receiving side. | Use a new uniqueId; do not resend the same submission unchanged. |
XDSMissingDocument | Metadata references a document that was not included in the submission. | Include the referenced document, or remove its metadata, and resubmit. |
XDSMissingDocumentMetadata | A MIME/MTOM document part has no corresponding metadata. | Add the document's metadata and resubmit. |
XDSUnknownPatientId | The patient identifier is not recognized by the receiving side. | Verify the identifier and assigning authority (Patient Identification); correct and resubmit. |
XDSPatientIdDoesNotMatch | The patientId differs between the submission set and a document. | Make the identifiers consistent and resubmit. |
XDSNonIdenticalHash | A document's hash or size does not match the value declared in its metadata. | Recompute the hash and size from the actual content so they match, and resubmit. |
Error and Fault Terminology
This guide avoids the ambiguous term "SOAP error." For clarity:
SOAP Fault - a failure that prevents XDR message processing from occurring.
XDR application-level error - a failure reported within a successful SOAP response, using a RegistryResponse with a RegistryErrorList.
This distinction separates transport-level failures from application-level rejections. See Handling the Synchronous Response and Error Management .