Response Codes

Overview

In Sage Business Cloud Accounting, every request made to the API will return an HTTP status code. This provides immediate feedback on the success or failure of the request.

Below is a summary of the status codes returned by the Accounting API.

HTTP Code	Message	Description
200	OK	Call to the API is successful.
201	Created	An artefact has been successfully created from a POST request.
204	No Content	Successful call, but no response body is returned, i.e. on a DELETE request.
401	Unauthorized	Several reasons, i.e. credentials are invalid and cannot be authorised.
404	Not Found	The path/endpoint does not exist.
405	Method Not Allowed	A request has been made using the wrong HTTP verb.
415	Unsupported Media Type	The media/language being passed in the request is not supported.
422	Unprocessable Entity	Invalid data has been passed and the request can not be completed successfully.
429	Too Many Requests	Too many requests have been made against the API. This prompts a throttling error.
500	Internal Server Error	Dammit, you ran into a bug in our application.
503	Service Unavailable	One of our servers required to serve this request could not be reached. Please retry later.

Below are a list of the more common response codes

200 OK

Receiving a 200 - OK is confirmation that the call made to the API is a successful one. The body of the response will usually display either the data requested or confirmation of the details made by a POST or PUT request.

201 Created

A 201 - Created status code is confirmation that a POST request made to the API has been successful. This also confirms that the artefact has been successfully created as part of the request.

204 No Content

The 204 status code is returned when a call was successful, yet there is no data to be returned. Most often this happens when a DELETE request was made successfully. The message will state ‘No Content’ and the response body will be blank.

401 Unauthorized

A 401 - Unauthorized can be returned for several reasons, all of which prevent making a successful request due to issues with the authorization process.

One of the more common reasons will be when the access token has expired. This can be resolved by refreshing the access token, or, preventative, by evaluating the expires_in attribute and refreshing before the token becomes invalid.

The response will be provided in JSON and in most cases includes a message:

[
    {
        "$severity": "error",
        "$dataCode": "AccessTokenExpiredError",
        "$message": "Your Access token has expired.",
        "$source": "Authorization"
    }
]

Other causes may be:

• The token was revoked.
• The token is invalid, malformed or was not passed at all.
• The client application has read only access, but is conducting a write (POST, PUT or DELETE) request.
• The user or business was not found in the application’s database.
• The business has no valid subscription, i.e. the trial period expired.
• The user does not have access to the business.

When a 401 - Unauthorized is returned for one of the above reasons (when it is not for AccessTokenExpiredError) the user should be prompted to authorize again. All previously stored refresh tokens should then be removed from the client.

404 Not Found

If this response is returned the endpoint/path requested does not exist.

[
  {
    "$severity": "error",
    "$dataCode": "PathNotFound",
    "$message": "The requested path is not found.",
    "$source": "Gateway"
  }
]

405 Method Not Allowed

Not all verbs are appropriate to every endpoint. A response code of 405 - Method Not Allowed indicates that the HTTP verb used in the request does not exist. In order to check the available verbs refer to the API reference here.

[
  {
    "$severity": "error",
    "$dataCode": "MethodNotAllowed",
    "$message": "The requested method is not allowed on this path.",
    "$source": "Gateway"
  }
]

415 Unsupported Media Type

The 415 - Unsupported Media Type response code is returned when application/json is not used in the body of the request. The Accounting API only accepts application/json.

429 Too Many Requests

A 429 - Too Many Requests code will be returned if the client application exceeds our rate limits or exceeds its quota. This means it is hitting our API servers too heavily and to avoid a complete breakdown of our services the request was rejected. It may result in the client being required to wait up to 24 hours before a further successful request can be made.

We plan to switch to user/business/client based rate limiting and throttling, which will give you much more control on this behavior. Check this documentation or our blog for updates.

500 Internal Server Error

This response can be due to something unexpected happening on our side (a bug). We are constantly checking our logs and are working hard to fix these bugs. However, if this is blocking your development, please contact us and the issue will be reviewed, which may result in the bug receiving a higher priority.