Skip to main content

Pragmatic use of ITK3 response codes for generic FHIR receive programmes

This guidance clarifies the use of the application level ITK3 response codes associated with the Generic FHIR Receive (GFR) capability implemented by suppliers of principal or foundation IT systems in GP practices in England.

Background

The ITK3 specification provides details of the full range of ITK3 response codes, as perceived to be useful for all possible use cases. Not all are appropriate for use with the Generic FHIR Receive (GFR) capability and the current range of NHS Digital programmes dependent on the GFR.

This guidance makes specific relaxation recommendations for receivers, on the requirements set out in the ITK Response Codes for Generic Receive document.

These relaxations are specific to the current use cases for Digital Medicines, Transfer of Care and GP Connect and reflect the knowledge gained from witness testing activities conducted with GP Foundation IT suppliers that commenced in December 2019, and subsequent First of Type activities. The expectation is that as the GFR matures, compliance will move to greater alignment with the ITK Response Codes for Generic Receive document. Senders would still need to have the appropriate business processes in place to deal with the original ‘MUST’ set of ITK response codes. 


ITK3 response code usage

Key words as used in the table below are as described in RFC2119. Definitions are reproduced below for convenience.

Must

This word, or the terms 'required' or 'shall, means that the definition is an absolute requirement of the specification.

Must not

This phrase, or the phrase 'shall not', mean that the definition is an absolute prohibition of the specification.

Should

This word, or the adjective 'recommended', means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

Should not

This phrase, or the phrase 'not recommneded' mean that there may exist valid reasons in particular circumstances when the particular behaviour is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behaviour described with this label.

Value: 10001, Display: Handling specification error

Original guidance and conformance Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site
A generic error code which gives a minimum level of assurance that systems can share the minimum information relating to Handling Specification faults. The code ‘10001’ is mandatory to be supported and returned to sender. Note a more specific code must be returned where one exists for the error.  Must Must

Not applicable

This code can act as a handling error “catch-all” if more nuanced infrastructure codes have not been implemented.

Not applicable

Negative infrastructure acknowledgement still informs sender that there is a build error in message but is less precise about the nature of the error.

 

Value: 10002, Display: Infrastructure level response value – processing error

Original guidance and conformance Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site
 
Impact of relaxation for sender site

The handling specification flag for infrastructure level response is present but cannot be processed. For example, may be unreadable or contain an incorrect value. This code is mandatory to be supported. 

If the InfAckRequestedvalue received is not ‘true’ or ‘false’ the response code ‘10002’ must be returned to sender.

Must Should

Suppliers can behave as follows: 

- if value is correctly set, honour purpose of flag, i.e. send or not send response
- always send infrastructure responses irrespective of valid flag value
- end a 10002 or a generic negative response value if flag value cannot be processed

Sender could get back: 

- '10001' (generic) or
- '1000'2 or 
- '20013' (i.e. positive response because error is not treated as fatal)

 

Value: 10003, Display: Business level response value – processing error

Original guidance and conformance 
 
Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

The handling specification flag for business level response is present but cannot be processed. For example, may be unreadable or contain an incorrect value. This code is mandatory to be supported.

If the BusAckRequested value received is not ‘true’ or ‘false’ the response code ‘10003’ must be returned to sender.

Must  Should

Suppliers can behave as follows:

- if value is correctly set, honour purpose of flag, i.e. send or not send business response.
- always send business responses irrespective of valid flag value
- send a 10003 or a generic negative response value if flag value cannot be processed - if value is empty use 10001, if unrecognised use 20009

 

 

Value: 10004, Display: Message definition value - processing error

Original guidance and conformance  Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site
The handling specification value for Message Definition is present but cannot be processed. For example, may be unreadable or contain an incorrect value. This may also be returned when the message type is not supported (known) by the receiving system. This code must be supported, and the following values are applicable:  Must Not applicable Supplier may choose to implement a default handling behaviour if this value cannot be processed. Where a negative response code is not generated, the default handling behaviour should still allow the document to be rendered as a Human Readable Object (HRO). If it proves not possible for receiver to render sender’s message as a human readable object, then a negative response code would be returned to indicate a build problem. 

Transfer of Care – Emergency Care eDischarge Implementation Guide 2.6.0-beta. The value must be:

‘https://fhir.nhs.uk/STU3/MessageDefinition/ITK-EC-eDischarge-MessageDefinition-4’ 

Must Should

Suppliers can send:


- 10001 if value is empty
- 20013 (positive response) if value is unrecognised but message can be transformed to HRO

For this specific error, sender could get back:

- 10001 or 
- 10004 or
- 20013 (i.e. not reported as error)

Transfer of Care – Inpatient (Acute) Discharge eDischarge Implementation Guide 2.6.0-beta. 

The value must be:

‘https://fhir.nhs.uk/STU3/MessageDefinition/ITK-eDischarge-MessageDefinition-4’

Must  Should

Suppliers can send:

- 10001 if value is empty
- 20013 (positive response) if value is unrecognised but message can be transformed to HRO

For this specific error, sender could get back: 

-10001 or 
-10004 or 
-20013 (i.e. not reported as error)

Transfer of Care – Mental Health eDischarge Implementation Guide 2.6.0-beta.  

The value must be: ‘https://fhir.nhs.uk/STU3/MessageDefinition/ITK-MH-eDischarge-MessageDefinition-4’ 

Must  Should

Suppliers can send: 

- 10001 if value is empty
- 20013 (positive response) if value is unrecognised but message can be transformed to HRO

For this specific error, sender could get back: 

- 10001 or
- 10004 or
- 20013 (i.e. not reported as error)

Transfer of Care – Outpatient Letter Implementation Guide 2.6.0-beta. 

The value must be: ‘https://fhir.nhs.uk/STU3/MessageDefinition/ITK-OPL-MessageDefinition-4’

Must Should

Suppliers can send: 

- 10001 if value is empty
- 20013 (positive response) if value is unrecognised but message can be transformed to HRO

For this specific error, sender could get back: 

- 10001 or
- 10004 or
- 20013 (i.e. not reported as error)

Digital Medication – DM Emergency Medication Supply 

“https://fhir.nhs.uk/STU3/MessageDefinition/ITK-DM-EmergencySupply-MessageDefinition-1”  

If any other value is received the response code ‘10004’ must be returned unless is an incorrect version, then follow the guidance below for response code ‘10005’ 

Note: the GP writeback message string is TBA.

Must Should


Suppliers can send: 

- 10001 if value is empty
- 20013 (positive response) if value is unrecognised but message can be transformed to HRO

For this specific error, sender could get back: 

- 10001 or
- 10004 or 
- 20013 (i.e. not reported as error)

 

Value: 10005, Display: Message definition version value - processing error

Original guidance and conformance 
 
Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

The handling specification for Message Definition is present but the version is not supported by the receiving system. 

If the string received is correct but the version is incorrect, the response code ‘10005’ must be returned to sender.

Must Should

Suppliers can behave as follows:  

- send a 10001 if value is empty
- send 10004 if message definition value rather than version is checked
- send a 20013 (positive response) if version value is unrecognised but message can be transformed to HRO

For this specific error, sender could get back:

- 10001 or 
- 10004 or 
- 10005 or
- 20013 (i.e. not reported as error)

That is, if HRO cannot be created at receiver end, the sender would be informed via negative response code. 

 

Value: 10007, Display: Sender reference value - processing error

Original guidance and conformance Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

The handling specification string for Sender Reference is present but cannot be processed. For example, may be unreadable, contain an incorrect value or the use of Sender Reference is not supported by receiving system. 

For the current use cases if any value other than the SenderReference default value of “None” is received the response code ‘10007’ must be returned to sender.

Must Should Supplier can choose to ignore this field value entirely. That is, if value cannot be processed it is not essential that a 10007 response code (or other negative infrastructure response code) is generated from this state.

For this specific error, sender could get back:

- 10007 or 
- 20013 (i.e. not reported as error)

 

Value: 10008, Display: Handling specification business rule error

Original guidance and conformance  Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site
 

The Handling Specification usage does not match business rules for included payload. For example, an acknowledgement flag defined as mandatory by the payload specification is missing. 

This error code should not be used for current use cases as there are no defined process for the correct identification of these rules.


Not applicable for current use cases, may be required for future use cases.
Not applicable Not applicable Not applicable

 

Value: 10009, Display: Unreadable message received

Original guidance and conformance Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

A message has been received that is either corrupted or malformed and cannot be read by the receiving system.

The response code ‘10009’ must be supported and returned to sender.

Must Should How the supplier responds would depend on the level of corruption of the message or how malformed the XML is. If no read is possible, the action may just be to clear it from the MESH mailbox. 

Sender can expect back: 

- 10009 or 
- 20009 or  
- no application level ITK3 response

It is acknowledged that a non-10009 response makes it difficult for a sender to identify a corruption problem arising during transport since the message held at the sender end would be in a good state when inspected. However, any corruption would be considered extremely rare. If no ITK3 response code is returned for a message sent, the sender would need to consider contacting the recipient GP Practice and / or sending the message again.

 

Value: 10010, Display: Recipient type - processing error

Original guidance and conformance 
 
Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

The handling specification for Recipient Type is present but cannot be processed. For example, may be unreadable or contain an incorrect value. 

The response code ‘10010’ must be supported and returned to sender.

Must  Should

From a clinical safety perspective, Transfer of Care would expect GP Practice staff to treat all documents received as “For Action” (FA) rather than “For Information” (FI).  In effect the value set is immaterial.   

If a processing problem with Recipient Type is detected sender can choose not to return a negative infrastructure response code. 

Sender can expect back: 

- 10010 or
- 20013 (i.e. not reported as error)

 

Value: 20001, Display: Unrecognised recipient person

Original guidance and conformance 
 
Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site


The person referred to as the recipient in the ITK3 MessageHeader when present is not recognised. 

The response code ‘20001’ must be supported and must be returned to sender.

Must  Should

Supplier system may handle this scenario in a few ways: 

- if recipient has previously logged on to the GP practice system but may no longer work there, then document could be reassigned to an appropriate person (for example, usual GP or principal GP) and a 20013 would be generated
- if recipient has been defined with invalid Spine Directory Service ID code then could generate 20001

The sender does not have to name a recipient in the message. If it has done, and it is unrecognised by receiver, can expect the following response codes:

- 20001 or 
- 20013 (i.e. not reported as error)

 

Value: 20002, Display: Unrecognised recipient organisation

Original guidance and conformance 
 
Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

The organisation referred to as the recipient in the ITK3 MessageHeader when present is not recognised.

The response code ‘20002’ must be supported and returned to sender.

Must  Must Not applicable Not applicable

 

Value: 20003, Display: Unrecognised sender

Original guidance and conformance 
 
Original (ITK3)     Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

The organisation or person referred to as the sender in the ITK3 MessageHeader is not recognised. Note: This code should not be used where the domain makes use of the “GP look-up” functionality in MESH. 

This error code should not be used for current use cases due to the potential use of GP look-up.

Not applicable for current use cases Not applicable Not applicable Not applicable

 

Value: 20004, Display: Non approved file type received as an attachment

Original guidance and conformance Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site
 
Impact of relaxation for sender site

The Receiving system has received an attached file whose file type is not approved for the business domain. 

This error code should not be used for current use cases due to the fact no business domain has defined their non-approved attachment types.

Not applicable for current use cases, may be required in future use cases Not applicable Not applicable Not applicable

 

Value: 20005, Display: Unsupported file type received as an attachment

Original guidance and conformance Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

The receiving system has received an attached file which it does not support. 

Note: all receiving systems must support at least .pdf file extensions. 

The response code ‘20005’ must be supported and returned to sender.

Must Must Not applicable Not applicable

 

Value: 20006, Display: ITK3 header validation failure

Original guidance and conformance Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site
 
Impact of relaxation for sender site


The ITK3 header resources or elements are not correct or understandable. The ITK3 Bundle or ITK3 MessageHeader fail conformance against the FHIR schemas: http://hl7.org/fhir/STU3/fhir-all-xsd.zip or HAPI validation using the approved version of the HAPI libraries* 

*This will be the version used by the ITK3 Test Harness. 

Must Should
If the supplier feels their battery of validation tests will have picked up all infrastructure issues that would cause a problem in rendering the message to a HRO, and their approach is to not reject messages unnecessarily, then validation of the header may be ignored.

Sender can expect the following response codes:

- 10001 or 
- 20006 or 
- 20013 (i.e. problem not reported as error)

That is, sender will get back a negative response if message cannot be transformed to HRO.

 

Value: 20007, Display: Duplicate message received

Original guidance and conformance 
 
Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site
 

Bundle with this message identifier has already been processed. A Payload with this message identifier has already been received and processed by this recipient. A message with this message header.id has already been received and processed. 

As stated in the FHIR standard – An incoming message contains two identifiers: the Bundle.id and the MessageHeader.id. Each time a new message is created, it SHALL be assigned an identifier (MessageHeader.id) that is unique within that message stream. Note that since message streams are often merged with other streams, it is recommended that the identifier should be globally unique. This can be achieved by using a UUID or an OID. Each time a message is sent, the Bundle.id should be changed to a new value.   

See: http://hl7.org/fhir/STU3/messaging.html 

The response code ‘20007’ must be supported and returned to sender, and the message deemed to be a duplicate must be rejected regardless of the content of the payload.

Must Should

Supplier may provide a solution that requires manual intervention by the end-user in the GP practice to confirm duplicates. The receiver system would under this circumstance return a positive infrastructure code, i.e. 20013 prior to the business response code.   

The GP IT supplier must have a clinically appropriate workaround behaviour for this scenario and an entry in their Hazard Log to identify the clinical risk and the mitigations in place. 

A sender needs to have rigorous processes in place to avoid a duplicate message ID being used.

The sender can expect one of following response codes where the error exists: 

- 20007 or 
- 20013 (i.e. problem not reported as error)

 

Value: 20008, Display: Duplicate document received

Original guidance and conformance Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

Bundle with this document identifier has already been processed. A payload with this document identifier has already been received and processed by this recipient. 

As stated in the FHIR standard The document identifier (mandatory). This is found in Bundle.identifier and is globally unique for this instance of the document, and is never re-used, including for other documents derived from the same composition. 

See: http://hl7.org/fhir/STU3/documents.html

The response code ‘20008’ must be supported and returned to sender, and the document deemed to be a duplicate must be rejected regardless of the content of the payload.

Must  Should

Supplier may provide a solution that requires manual intervention by the end-user in the GP practice to confirm duplicates. The receiver system would under this circumstance return a positive infrastructure code, i.e. 20013 prior to the business response code.   

The GP IT supplier must have a clinically appropriate workaround behaviour for this scenario and an entry in their Hazard Log to identify the clinical risk and the  mitigations in place. 
 

A sender needs to have rigorous processes in place to avoid a duplicate message ID being used.

The sender can expect one of following response codes: 

- 20008 or 
- 20013 (i.e. problem not reported as error)

 

Value: 20009, Display: Payload validation failure

Original guidance and conformance 
 
Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site
 
Impact of relaxation for sender site
 

The payload is not correct or understandable. The payload fails conformance test against the FHIR schemas: http://hl7.org/fhir/STU3/fhir-all-xsd.zip

or HAPI validation using the approved version of the HAPI libraries*

*This will be the version used by the ITK3 Test Harness. The response code ‘20009’ must be supported and returned to sender.

Must Should If the supplier feels their battery of validation tests will have picked up all infrastructure issues that would cause a problem in rendering the message to a HRO, and their approach is to not reject messages unnecessarily, then payload validation may be ignored. 
This code can also act as a payload error “catch-all” where more nuanced codes have not been implemented.

Sender can expect back from GP Practice either:

- 20009 or
- 20013  (i.e. problem not reported as error)

That is, sender will get back a negative response if message cannot be transformed to HRO.

 

Value: 20010, Display: Unrecognised payload recipient organisation

Original guidance and conformance Original (ITK3)     Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

The recipient organisation identified in the payload, is not supported by this end point (receiving system). 

The response code ‘20010’ must be supported and returned to sender.

Must Must Not applicable Not applicable

 

Value: 20011, Display: Unrecognised payload recipient person

Original guidance and conformance 
 
Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

The recipient person identified in the payload, is not supported by this end point (receiving system). 

The response code ‘20011’ must be supported and returned to sender. 

For ToC, 20011 is analogous to an error with the recipient in the letter, and 20001 to an error with the recipient in the envelope.

Must Should

Supplier may treat this in a similar fashion to the previous scenario code 20001 relating to unrecognised recipient in the ITK3 MessageHeader.

That is, document may be reallocated to another member of staff in the GP Practice.

A positive infrastructure code (20013) would be generated rather than 20011.

The sender does not have to name a recipient in the message. If it has done, and the recipient is not recognised at the GP Practice end then the sender could receive one of the following codes: 

- 20011 or 
- 20013 (i.e. problem not reported as error)

 

Value: 20012, Display: Unauthorised sender

Original guidance and conformance 
 
Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site


The receiving system identified in the payload is configured to reject messages from unauthorised senders. This code should not be used where the domain makes use of the 'GP look-up' functionality in MESH.

The response code 20012 should not be used.

Not applicable Not applicable Not applicable Not applicable

 

Value: 20013, Display: Success

Original guidance and conformance 
 
Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

The message has been processed successfully. A response will be returned stating the fact. However, the message may still fail after further processing and result in another response if the business level response request flag has been sent to 'true'. 

The response code ‘20013’ must be supported must be returned to sender.

Must Must Not applicable Not applicable

 

Value: 20014, Display: Unable to process replacement document

Original guidance and conformance Original (ITK3)     Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

A replacement document was received, but the receiver could not process the new document correctly and has therefore marked the new and original documents as “bad” on its system.

The response code ‘20014’ must be supported and returned to sender.

Must Should

The received document may be in a state where processing cannot be done to recognise it as a replacement. Where processing is possible to the point where the document is confirmed as a replacement, then suppliers should make every effort to indicate to staff that the initial document (i.e. that intended to be replaced) needs to be treated as “bad” to prevent GP Practice staff placing undue reliance on its content for patient care. 

The GP IT supplier must have a clinically appropriate workaround behaviour for this scenario and an entry in their hazard log to identify the clinical risk and the  mitigations in place.

As the sender previously sent a successful original message, the likelihood of not being able to process the replacement document is considered low. 

For this error, the sender can expect back from the GP Practice system the following:

- 10001 negative catch-all infrastructure code or
- a more nuanced code for the specific processing problem such as a 10009 for bad XML, or  
- 20014 to show the error relates to a failed replacement or
- two negative infrastructure response codes in the same ACK message - this would be the more nuanced error code such as 10009, and 20014 to indicate it relates to a replacement document

It is important that sender sites have adequate auditing capabilities so negative response codes can be traced back to the sent messages and any replacement document problems identified swiftly. When the sender identifies the response message as relating to a replacement document then they would need to urgently contact the GP practice via telephone to address any patient safety risks.

 

Value: 20015, Display: Message too large

Original guidance and conformance Original (ITK3)     Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

Not applicable - new response code

Not applicable Must

Non-implementation may result in processing problems for the GP Foundation IT system when large messages are received.  This could require GP Practice staff to contact the GP IT supplier’s Support Desk for manual rectification.

If a large message file is created due to the use of attachments, and no checks are made on size prior to sending then the message initiator may receive no ITK3 response code at all if GP IT supplier does not support a 20015.

 

Value: 30001, Display: Patient known here, for example patient is registered here

Original guidance and conformance  Original (ITK3)     Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site
The response code ‘30001’ must be supported and returned to sender.  Must Must Not applicable Not applicable

 

Value: 30002, Display: Patient not known here, also known as 'patient record not present in system'

Original guidance and conformance Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site
The response code ‘30002’ must be supported and returned to sender. Must Must Not applicable Not applicable

 

Value: 30003, Display: Patient no longer at this clinical setting

Original guidance and conformance  Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site

The response code ‘30003’ must be supported and returned to sender.
Must Must Not applicable Not applicable

 

Value: 30004, Display: Patient known here and recently deceased (i.e. patient record current in GP practice system at time of patient’s death and deduction subsequently occurred for this reason)

Original guidance and conformance  Original (ITK3) Relaxed (ITK3) Impact of relaxation for receiver (GP) site Impact of relaxation for sender site
Implementers must support this code at the earliest opportunity. Not applicable - new response code Must

Non-implementation means that the GP Practice IT system would return a 30003 response if the patient had been deducted due to their death. GP Practice staff would then have to receive the message via another (non-FHIR) route and manually associate this correspondence with the patient’s record to complete it. When implemented, use would be during a defined time window only. The start of the time window would be the date of the patient’s death and the end of the window just prior to 6 months after this date.  

When the date of receival of the FHIR message falls outside this window (i.e. 6-months or later), a code 30003 would be returned to the sender.

Non-implementation means that the sending organisation would need to contact the GP practice and agree an alternative non-FHIR means of sending the correspondence to the GP practice. 

Last edited: 30 March 2021 1:34 pm