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 docid\ za3pmlbsxejas5vduvf55 for guidance on producing errors) for a complete failure response, see example 4 8 1 ( handling the synchronous response docid\ xz0mts w6fvt5wxkvd q0 ) delivery outcome failures reported asynchronously dsn failures and delivery timeouts are covered in delivery status notification (dsn) docid\ daga7uw8atariylz3rtu9 and xdr based messaging best practices docid\ za3pmlbsxejas5vduvf55 ) 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 docid\ za3pmlbsxejas5vduvf55 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 docid\ xyqrosgpz8458uzh0p8su and error management docid\ za3pmlbsxejas5vduvf55 ) 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 docid\ za3pmlbsxejas5vduvf55 ) xdsregistrymetadataerror required metadata is missing, malformed, or invalid correct the metadata ( message metadata docid\ xz0mts w6fvt5wxkvd q0 ) 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 docid\ xz0mts w6fvt5wxkvd q0 ); 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 docid\ xz0mts w6fvt5wxkvd q0 and error management docid\ za3pmlbsxejas5vduvf55