Managing errors returned by the Xure API

Understanding status codes

The Xure API uses standard HTTP status codes to indicate the overall outcome from the API method being called.

Status Code Outcome
200 OK Method processed successfully
201 Created Method processed successfully and content was created. The Location header gives the URL for the content that was created. Generally this is an API endpoint that can be used to obtain information on or further modify the content.
204 No Content Method processed successfully with no response being returned
400 Bad Request The format of the request data could not be understood. This is because the supplied data does not match the request schema for the API method for the specified content type; elements of the request data failed validation or were unsuitable for the method.
401 Unauthorized Access to the API endpoint is restricted and no authentication credentials were supplied with the request
403 Forbidden Access to the API endpoint is restricted and the supplied authentication credentials do not grant the permissions required
404 Not Found The API endpoint URL does not exist. If the URL contains path parameters, one of the supplied parameters may not map to an existing entity.
405 Method Not Allowed The HTTP method specified in the request is not supported for the API endpoint. This is because the method (GET, POST etc.) doesn't match those specified for any of the API methods defined for the endpoint.
406 Not Acceptable The requested content type for the response, as given the Accept header of the request, is not supported by the API method.
429 Too Many Requests The client has exceeded their allocated API request quota
500 Server Error An unexpected error occured on the server whilst processing the request

Extended error details

Where multiple errors were raised, or more detail can be provided, the response contains error data encoded in the requested format. Each error report within the response includes the following parameters:

Parameter Description
type The general error type: either DataError, OperationError or ServerError
code A unique code string for this class of error
parameter If the error relates to a specific request parameter this gives the parameter name
message A human-friendly description of the error
linenumber If the error can be traced to a specific location in the request data this gives the line number
lineposition If the error can be traced to a specific location in the request data this gives the character index within the line

The precise format of this depends on the requested content type. Examples are given below of responses containing extended error details in both XML and JSON formats:

HTTP/1.1 400 Bad Request
Content-Type: text/xml; charset=utf-8

<errors>
  <error>
    <type>DataError</type>
    <code>DataError:SchemeIdentifier:InvalidIdentifier</code>
    <parameter>SchemeIdentifier</parameter>
    <message>Invalid scheme identifier</message>
  </error>
</errors>
An error response returned in XML format for an invalid identifier given for the SchemeIdentifier in the request data
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "errors":[
    {
      "type": "DataError",
      "code": "DataError:SchemeIdentifier:InvalidIdentifier",
      "parameter": "SchemeIdentifier",
      "message": "Invalid scheme identifier"
    }
  ]
}
The same error response in JSON format

Error types and codes

The guidance for every API endpoint lists the expected range of HTTP status and error codes that may be returned in response to a request.

There are three overall types of error details returned by the API:

Error Type Condition
DataError This indicates a problem with the data provided in the request. This could be due to:
  • the request is not valid XML or JSON
  • required parameters missing from the request
  • unexpected parameters included in the request, or in an unexpected location within the request
  • badly-formatted parameter values, for example a date / time that is not ISO8601 format
  • valid parameter values that are not appropriate given the context of the request
OperationError The request could not be completed due to an expected reason, for example:
  • The entity being acted upon is not in a valid state given the operation requested
ServerError The request could not be completed due to an unexpected reason.

Further categorisation of the error can be acheived by checking the returned code. This is an alpha-numeric string made from one or more parts delimited by colon characters. The first part of the code gives the error type (as described above). If the error relates to a specific request parameter then this is followed by the parameter name. The final part is a unique sub-code that describes the precise error condition.

For example, taking the error code provided in the example responses above:

DataError:SchemeIdentifier:InvalidIdentifier

This indicates that the error is a data issue relating to the SchemeIdentifier parameter, and specifically, that an invalid identifier has been provided.