HTTP Response Codes

In true REST style, the Xero API will return different http response codes depending on the outcome of processing the request message.

When your application receives a response from the API, you should first check the http response code before trying to decode the response body. This will save problems such as trying to decode html data as json!

We also recommend you log Xero API error responses and show a friendly message to the user rather than the actual API exception message.

Note: The API may not return the response message that you are expecting – even the formatting could be different. OAuth errors will return form-encoded data. Client SSL certificate errors will return an html page. When the API is offline, you’ll get just plain text. Everything else should be xml or json depending on what you requested.

Note: A customer may disconnect your appliction from within Xero at anytime so at the very least you should implement functionality to handle a 401 error and allow a customer to easily reauthorize your application.

Below we’ve listed the most common HTTP response codes returned from the Xero API

200 OK

Successful request.

HTTP/1.1 200 OK
Date: Tue, 19 Apr 2011 00:45:18 GMT
Content-Type: text/xml; charset=utf-8
Content-Length: 1088

<Response>
  <Id>...</Id>
  <Status>OK</Status>
  <ProviderName>...</ProviderName>
  <DateTimeUTC>...</DateTimeUTC>
  ...
</Response>

or..

HTTP/1.1 200 OK
Date: Tue, 19 Apr 2011 00:45:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 771

{
  "Id": "...",
  "Status": "OK",
  "ProviderName": "...",
  "DateTimeUTC": "...",
  ...
}

400 Bad Request

The request message was not valid.

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

<ApiException>
  <ErrorNumber>10</ErrorNumber>
  <Type>ValidationException</Type>
  <Message>A validation exception occurred</Message>
  <Elements>
    ...
  </Elements>
</ApiException>

The following list are sample messages that can occur:

Invoice is a template and cannot be paid directly
Payment amounts must be positive amounts
Payment amount exceeds the amount due on this invoice
Payments can only be made against Authorised invoices
You can only record payments against AR or AP invoices
Invoice could not be found
Account code cannot be an empty value
Account could not be found
Account type is invalid for making a payment to/from
Credit note not of valid type for creation
Contact name or number are not unique, these must be unique values
Contact cannot be empty.
Contact status is invalid
Users Organisation is not subscribed to currency USD
Invoice # must be unique.
Line item quanitites cannot be negative
Unable to find contact with the specified contact Id
Input string was not in a correct format.
Unable to find the tax type TAX004

401 Unauthorized

There was something wrong with the authorization credentials.

HTTP/1.1 401 Unauthorized
Content-Type: text/html; charset=utf-8
Content-Length: 141

oauth_problem=xxxxxxxxxxxxxxxx&oauth_problem_advice=xxxxxxxxxxxxxxxxxx

403 Forbidden

The client SSL certificate was not valid.

HTTP/1.1 403 Forbidden
Content-Type: text/html; charset=utf-8
Content-Length: 141

<html>
  ...
</html>

404 Not found

The resource you have specified cannot be found

HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
Content-Length: 47

The resource you're looking for cannot be found

418 I’m a teapot

The coffee request cannot be processed

HTTP/1.1 418
Content-Type: text/html; charset=utf-8
Content-Length: 13

I'm a teapot!

501 Not Implemented

The method you have called has not been implemented (e.g. POST Organisation)

HTTP/1.1 501 Not Implemented
Content-Type: text/xml; charset=utf-8
Content-Length: 275

<ApiException>
  <ErrorNumber>20</ErrorNumber>
  <Type>ApiMethodNotImplementedException</Type>
  <Message>The Api Method called is not implemented</Message>
</ApiException>

503 Not available

API is currently unavailable – typically due to a scheduled outage – try again soon

HTTP/1.1 503 Service Unavailable
Content-Type: text/plain; charset=utf-8
Content-Length: 275

The Xero API is currently offline for maintenance

Developer