HTTP Response Codes & Errors

Codes Summary

A summary of HTTP Response Codes returned by the Xero HQ API is shown below.
HTTP Code Summary Description
200 OK Successful API call
201 Created Resource created
204 No Content The server has successfully fulfilled the request and that there is no additional content to send in the response
400 Bad Request A bad request or a validation exception has occurred
401 Unauthorized Invalid authorization credentials
404 Not Found The resource you have specified cannot be found
500 Internal Server Error An unhandled error with the Xero API. Contact the Xero API team if problems persist
501 Not Implemented The method you have called has not been implemented (e.g. GET /alerts)
503 Rate Limit Exceeded The API rate limit for your pracitce/application pairing has been exceeded.
503 Service Unavailable API is currently unavailable – typically due to a scheduled outage – try again soon.


If the returned HTTP Status Code is 4xx or 5xx, the API Consumer should manage the retries. Take into account that a 503 might happen due to a Rate Limit, with will cause the retry not to work.


HTTP 4XX responses may optionally return the content type application/problem+json as a common standard, defined in RFC 780. For example:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

    "type": "/errors/alerts/invalid-field",
    "title": "Field in alert body could not be recognised"
    "detail": "Field 'Type' is invalid"

Data Types


All timestamps are specified in ISO 8601 format e.g. YYYY-MM-DDTHH:MM:SSZ


Numeric values should be as specified in section 2.4 Numbers.