Glossary Item Box

Government Gateway 2.2.0 (MR-01) ISV Developer Help (Doc Version 06/03/08) | Send comments on this topic.

# SUBMISSION_ERROR

# Message Source/Destination

Gateway to Portal/Client application

#

# Processing

The SUBMISSION_ERROR message can be returned for all client initiated messages.

- SUBMISSION_REQUEST
- SUBMISSION_POLL
- DELETE_REQUEST
- DATA_REQUEST

The GovTalkErrors element will describe the error(s). The SUBMISSION_ERROR will only be generated when the client message cannot be processed by the Gateway. This may include syntax checks on the entire GovTalkMessage.

This message can be returned by the Gateway for a number of reasons:

- An invalid document is submitted that fails DSP schema/protocol validation
- The Gateway Service has been disabled for scheduled downtime of a back-end system – an Internal error.
- The back-end system does not respond in a timely manner.

For example, as illustrated, the initial SUBMISSION_REQUEST may be missing the Class element, or a SUBMISSION_POLL may be missing a CorrelationID. Either of these errors is classed as fatal since the Gateway does not have sufficient information to process the message. In this case, the Gateway will return a SUBMISSION_ERROR message with an Error/Type of fatal.

The behaviour of the client system depends on the point at which the error occurred. If the error occurred on a SUBMISSION_REQUEST, the client should correct the error and resubmit the message. If it occurs later in the sequence, the client application must continue the sequence using the value of CorrelationID from the original SUBMISSION_RESPONSE.

Note: the DATA_REQUEST verb can be used to identify those submission sequences that have not completed successfully.

#

# Message Structure

GovTalkMessage | MANDATORY. A default namespace specified as “http://www.govtalk.gov.uk/CM/envelope”.
EnvelopeVersion | MANDATORY. Set to 2.0 or 1.0 to the mirror EnvelopVersion value in the client message that failed.
Header | MANDATORY.
MessageDetails | MANDATORY.
Class | MANDATORY. Identifies the class of document for which the error is raised. If the error was encountered before this is determined the generic UndefinedClass value will be returned.
Qualifier | MANDATORY. Set to error.
Function | MANDATORY. Set to submit.
TransactionID | MANDATORY. If the client SUBMISSION_REQUEST supplied a TransactionID it will be returned in this element.
CorrelationID | MANDATORY. Depends on the message that caused the error: For SUBMISSION_REQUEST – Provided by Gateway For SUBMISSION_POLL – This would normally be the value provided in the previous SUBMISSION_ACKNOWLEDGE For DELETE_REQUEST - This would normally be the value provided in the associated SUBMISSION_RESPONSE For DATA_REQUEST - Provided by Gateway
ResponseEndPoint | MANDATORY. Contains a valid HTTP end point address. The PollInterval attribute will be set to an integer value. The Portal/client application can issue follow-on messages to this end-point after the recommended delay (in seconds) which is indicated by the value in the PollInterval attribute.
GatewayTimestamp | MANDATORY. Contains the time the message was generated.
SenderDetails | MANDATORY. Element will be empty.
GovTalkDetails | MANDATORY.
Keys | MANDATORY. Key elements will not be present.
GovTalkErrors | MANDATORY. Can include multiple Error elements.
Error/RaisedBy | MANDATORY. Set to Gateway.
Error/Number | MANDATORY. Contains a published error code value.
Error/Type | MANDATORY. Set to fatal.
Error/Text | MANDATORY. Contains additional information which should be of assistance in correcting the problem.
Error/Location | MANDATORY. Contains location related information – can be empty.
Body | MANDATORY. Element will be empty.

# Samples

The mandatory elements within the following sample submission error are shown in bold while optional elements appear in normal type.
<?xml version="1.0"?> <GovTalkMessage xmlns="http://www.govtalk.gov.uk/CM/envelope"> <EnvelopeVersion>1.0</EnvelopeVersion> <Header> <MessageDetails> <Class>MOSWTSC2</Class> <Qualifier>error</Qualifier> <Function>submit</Function> <TransactionID>20021202ABC</TransactionID> <CorrelationID>1DF257B5CD23F4A5B6C7D8E9F102932</CorrelationID> <ResponseEndPoint PollInterval=”2”> https://secure.gateway.gov.uk/submission </ResponseEndPoint> <GatewayTimestamp>2001-01-31T10:20:18.345</GatewayTimestamp> </MessageDetails> <SenderDetails/> </Header> <GovTalkDetails> <Keys/> <GovTalkErrors> <Error> <RaisedBy>Gateway</RaisedBy> <Number>1020</Number> <Type>fatal</Type> <Text>A meaningful description of the error</Text> <Location></Location> </Error> </GovTalkErrors> </GovTalkDetails> <Body/> </GovTalkMessage>

© Crown Copyright 2008. All rights reserved