Error Responses

SPCM will reject submissions which do not meet the technical requirements, returns which do not conform to the schema, and may also reject returns which contain invalid data.

When an error occurs, SPCM will provide information about the cause of the error in a JSON response. This section describes the format of the JSON response, and the situations in which SPCM will reject a return.

The importance of handling errors

The rules SPCM applies to submissions are presently nearly all simple validity checks which do not make reference to any information other than what is contained in the return. This means a well-implemented submitting system should be able to prevent almost all these errors occurring by validating data before attempting to submit it to SPCM.

The main exception to this is the MessageValidationFailed error with code InvalidEmployerData. This error indicates that the employer's socialSecurityNo, taxRef and name are not consistent with any employer known to the Revenue Service. Submitting systems cannot know if this error will occur except by attempting a live transmission.

To handle this situation, and also to handle new validation rules which may be added in future, submitting systems must be designed to handle error conditions and present the error messages to the user in a helpful way.

Response format

If a return submission to the API succeed, then SPCM will response with HTTP status code 200. This means the return was accepted and stored by the system.

If a return is submitted to SPCM which is malformed or contains invalid data, then SPCM will respond with HTTP status code 400. This means the return was rejected and discarded. The submitting system must therefore check the HTTP status code in the response, and alert the user if this is anything other than 200.

The HTTP response body contain a JSON representation of the exception, the content of which will differ depending on the type of exception and the detailed reason. The submitting system must present the information in the response to the user as best it can, so that they have a chance to diagnose and fix the error themselves.

Error codes

The JSON response for these errors always has the following structure:


            {
    "code": "APIKeyNotProvided",
    "message": "No API key was provided. You must provide an API key in the HTTP header 'X-API-Key'."
}

"code": A code indicating the type of error.
"message": The description of the error.

The following error codes are currently defined:

APIKeyNotProvided: No API key was provided. You must provide an API key in the HTTP header 'X-API-Key'.
APIKeyInvalid: The API key does not meet the length requirement (between 16 and 64 characters in length).
RequestBodyMissing: The request body was empty (it should contain the JSON for the return).
JSONParseFailed: The body could not be parsed as valid JSON (see below for an example).
SPCMMessageVersionPropertyMissing: The spcmMessageVersion property in the JSON body is missing (it should be a property of the root of the message object).
SPCMMessageVersionInvalid: The spcmMessageVersion property is invalid (it should be a numeric version in form 'x.y').
SPCMMessageVersionNotSupported: The spcmMessageVersion supplied does not correspond to a supported version of the schema.
MessageTestFlagNotAsExpected: A test message was submitted to the live endpoint, or vice versa.
UTF8DecodeFailed: The request body could not be decoded as UTF-8 (JSON must be UTF-8 encoded).
JSONValidationFailed: The submitted return is well-formed JSON, but does not conform to the SPCM JSON message schema indicated by the spcmMessageVersion property. The JSON response (documented below) will contain additional information about the error.
MessageValidationFailed: The submitted return conforms to the JSON schema, but the return message itself is not logically consistent or contains invalid data. The JSON response (documented below) will contain additional information about the error.

JSON parse failed

This type of exception occurs if the submitted return is not well-formed JSON. Submitting systems which use a suitable JSON serializer should not receive this type of error.

Submission:


            This is not a JSON file!

Response:


            {
    "code": "JSONParseFailed",
    "message": "'T' is an invalid start of a value. Path: $ | LineNumber: 0 | BytePositionInLine: 0."
}

"code": The value "JSONParseFailed" indicates that this is a JSON parse failure.
"message": The description of the parse error which was returned by the SPCM JSON deserializer.

JSON validation failed

This type of exception occurs if the submitted return is well-formed JSON, but does not conform to the SPCM JSON message schema indicated by the spcmMessageVersion property.

Submission:


            {
  "$schema": "https://spcm.gov.gg/schemas/0.3/message.schema.json",
  "spcmMessageVersion": "0.3",
  "effective": "Thursday",
  "senderEmail": "07781 123456",
  "senderName": "Test",
  "softwareAgent": "JSON Editor",
  "type": "Revenue_EmployerReturn",
  "test": true,
  "purposes": [
    "SecondaryPensions",
    "EconomicStatistics"
  ],
  "pensionSchemes": [],
  "employers": [
    null
  ]
}

Response:


            {
    "messages": [
        {
            "location": "/senderEmail",
            "message": "Value does not match format \"email\"",
            "code": "JSONSchemaError"
        },
        {
            "location": "/effective",
            "message": "Value does not match format \"date-time\"",
            "code": "JSONSchemaError"
        },
        {
            "location": "",
            "message": "Required properties [\"coverage\"] are not present",
            "code": "JSONSchemaError"
        },
        {
            "location": "/employers/0",
            "message": "Value is \"null\" but should be \"object\"",
            "code": "JSONSchemaError"
        }
    ],
    "code": "JSONValidationFailed",
    "message": "JSON schema validation failed"
}

"code"

The value "JSONValidationFailed" indicates that this is a JSON schema validation failure.

"message"

This will always be "JSON schema validation failed" for this type of exception.

"messages"

An array of schema validation errors:

"location": The location in the JSON file where the validation error occurred. The value is the string representation of the JSON pointer to the element which is invalid.
"message": A description of the validation error.
"code": For schema validation errors, this is always "JSONSchemaError".

Message validation failed

This type of exception occurs if the submitted return conforms to the JSON schema, but the return message itself is not logically consistent or contains invalid data.

Please note: The validation rules in SPCM will be extended over time, in order to prevent obviously incorrect data being submitted to the Revenue Service. This means that the API in future may return message codes which are not listed here, and messages which are currently valid may be considered invalid in the future. Systems using the SPCM API should be capable of displaying human-readable feedback about validation messages to the user, even if the response contains code values other than those presently defined in this specification.

Submission:


            {
  "$schema": "https://spcm.gov.gg/schemas/0.3/message.schema.json",
  "effective": "2022-03-22T15:19:02Z",
  "spcmMessageVersion": "0.3",
  "senderEmail": "joseph@acme.gg",
  "senderName": "Joseph Administrator",
  "softwareAgent": "Acme Payroll v1.44",
  "type": "Revenue_EmployerReturn",
  "test": true,
  "purposes": [
    "SecondaryPensions",
    "EconomicStatistics"
  ],
  "coverage": [
    {
      "year": 2022,
      "frequency": "Monthly",
      "period": 1
    },
    {
      "year": 2022,
      "frequency": "Monthly",
      "period": 2
    },
    {
      "year": 2022,
      "frequency": "Monthly",
      "period": 3
    }
  ],
  "pensionSchemes": [
    {
      "id": "A1",
      "providerCountry": "GG",
      "countryProviderRef": "123456",
      "providerName": "Acme Pensions",
      "name": "Acme Gold Scheme",
      "taxRef": "0R123456",
      "type": "DefinedContribution"
    }
  ],
  "employers": [
    {
      "id": "5363",
      "name": "Acme Widgets",
      "socialSecurityNo": "987654",
      "employees": [
        {
          "id": "12345",
          "dateOfBirth": "1980-01-01",
          "socialSecurityNo": "GY123456",
          "firstName": "Joseph",
          "lastName": "Bloggs",
          "purposes": [
            "SecondaryPensions",
            "EconomicStatistics"
          ],
          "fullTimeEducation": false,
          "islandOfResidence": "Guernsey",
          "secondaryPensionsOptedOutUntil": null,
          "pay": [
            {
              "year": 2022,
              "frequency": "Monthly",
              "period": 2,
              "earnings": 1234.56,
              "pensionSchemeId": "A8",
              "pensionEmployerAmount": 126.45,
              "pensionEmployeeRegularAmount": 23.00,
              "pensionEmployeeAdditionalAmount": 0.00,
              "employerSSContributions": 5.00,
              "hoursWorked": 5,
              "occupationCode": "4133"
            },
            {
              "year": 2022,
              "frequency": "Monthly",
              "period": 2,
              "earnings": 1234.56,
              "pensionSchemeId": "A8",
              "pensionEmployerAmount": 126.45,
              "pensionEmployeeRegularAmount": 23.00,
              "pensionEmployeeAdditionalAmount": 0.00,
              "employerSSContributions": 5.00,
              "hoursWorked": 5,
              "occupationCode": "4133"
            },
            {
              "year": 2022,
              "frequency": "Monthly",
              "period": 5,
              "earnings": 2345.78,
              "pensionSchemeId": "A1",
              "pensionEmployerAmount": 234.56,
              "pensionEmployeeRegularAmount": 23.00,
              "pensionEmployeeAdditionalAmount": 45.00,
              "employerSSContributions": 129.00,
              "hoursWorked": 12,
              "occupationCode": "9999"
            }
          ]
        },
        {
          "id": "12345",
          "dateOfBirth": "1981-03-31",
          "firstName": "Harriet",
          "lastName": "Bloggs",
          "pay": [],
          "purposes": []
        }
      ]
    }
  ]
}

Response:


            {
    "messages": [
        {
            "location": "/employers/0",
            "message": "Invalid employer data",
            "code": "InvalidEmployerData"
        },
        {
            "location": "/employers/0/employees",
            "message": "Multiple employees reported with the Id 12345",
            "code": "DuplicateEmployeeId"
        },
        {
            "location": "/employers/0/employee/0/pay",
            "message": "Multiple pay records for 2022 month 2",
            "code": "DuplicatePayRecord"
        },
        {
            "location": "/employers/0/employee/0/pay/0/pensionSchemeId",
            "message": "Pension scheme with Id A8 not found",
            "code": "PensionSchemeIdNotFound"
        },
        {
            "location": "/employers/0/employee/0/pay/1/pensionSchemeId",
            "message": "Pension scheme with Id A8 not found",
            "code": "PensionSchemeIdNotFound"
        },
        {
            "location": "/employers/0/employee/0/pay/2",
            "message": "Pay record relates to a period not covered by this message",
            "code": "PayPeriodNotCovered"
        },
        {
            "location": "/employers/0/employee/0/pay/2/occupationCode",
            "message": "Occupation code 9999 not valid",
            "code": "OccupationCodeInvalid"
        }
    ],
    "code": "MessageValidationFailed",
    "message": "Message validation failed"
}

"code"

The value "MessageValidationFailed" indicates that the message failed checks for logical consistency and data content.

"message"

This will always be "Message validation failed" for this type of exception.

"messages"

An array of message validation errors:

"code"

This code can be used to identify the type of validation error. The codes are:

InvalidEmployerData: The employer's socialSecurityNo, taxRef and name are not consistent with any employer known to the Revenue Service.
PayPeriodNotCovered: The employee's pay period is not one of those listed in the coverage section of the return.
PensionSchemeIdNotFound: The pensionSchemeId for this employee has not been reported in the pensionSchemes array.
OccupationCodeInvalid: The occupationCode is not a valid code according to the list at https://www.gov.gg/ocodes.
DuplicatePayRecord: There are duplicate pay records for the employee for a particular period.
DuplicateEmployer, DuplicateEmployee, DuplicatePensionScheme: Records of the relevant type have duplicate Ids within this return.
PurposeNotSupported: The purpose specified, while defined in the JSON schema, is not supported by the SPCM system (e.g. the PensionProvider purpose).
MessageVersionNotSupported: The message version specified cannot be used for conveying a message of this type (the error message property will contain more information).