Error Handling

Each operation will return an HTTP response to indicate the result of the operation.

200	The operation succeeded. Note that many operations return a standard type of response with Success and Description fields. If Success is false then this should be treated the same as if the response was a HTTP 400 error (with the Description field containing the error message).
304	Used with caching to indicate that the cached copy is still valid.
400	The request is believed to be invalid in some way. The response body will contain an error message. You should display the error message to the user.
401	An OAuth authentication failure occurred. You should ask the user to log in again.
429	Your rate limit has been exceeded. Your rate limit will reset at the start of the next hour. You should not attempt to make any more calls until then.
500	A server error occurred. You should display a generic "whoops" error message to the user.

Error details are sent in the format dictated by the URL.

Handling 429 responses

Each application and member within that application are given a fixed allocation of calls per hour. See Rate Limiting. When you receive a 429 response code from the API it means you have exceeded the hourly calls allocated to that member for the given application. At this point you should stop attempting to make calls to the API until the top of the next hour when rate limits are reset.

XML error response example

HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Pragma: no-cache
Content-Type: text/xml
Server: Microsoft-IIS/7.0
Date: Fri, 25 Sep 2009 02:57:36 GMT
Content-Length: 222
<code class="language-xml">
<ErrorResult xmlns="http://api.trademe.co.nz/v1" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <Request>https://api.trademe.co.nz/v1/categories/11111.xml</Request>
   <ErrorDescription>Category 11111 was not found</ErrorDescription>
</ErrorResult>
</code>

JSON error response example

HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json
Server: Microsoft-IIS/7.0
Date: Fri, 25 Sep 2009 02:57:36 GMT
Content-Length: 222
<code class="language-json">
{
   Request: "https://api.trademe.co.nz/v1/categories/11111.json",
   ErrorDescription: "Category 11111 was not found"
}
</code>

Error Codes

The Trade Me API now supports error codes. Error codes can now be returned as part of a standard 400 response within the ErrorResult object.

NOTE: Not all responses include error codes.

XML error response with error code example

HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Pragma: no-cache
Content-Type: text/xml
Server: Microsoft-IIS/7.0
Date: Fri, 25 Sep 2009 02:57:36 GMT
Content-Length: 222
<code class="language-xml">
<ErrorResult xmlns="http://api.trademe.co.nz/v1" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <Request>https://api.trademe.co.nz/v1/Listings/1.xml</Request>
   <ErrorDescription>Listing id 1 is not valid</ErrorDescription>
   <Error>
      <Code>ListingNotFound</Code>
      <UserDescription>The listing you requested was not found.</UserDescription>
      <DeveloperDescription>The listing requested was not found. This is because the listing id is incorrect.</DeveloperDescription>
      <ErrorData>
         <ErrorDataItem>
            <Name>ListingId</Name>
            <Value>1</Value>
         </ErrorDataItem>
      </ErrorData>
   </Error>
</ErrorResult>
</code>

JSON error response with error code example

HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json
Server: Microsoft-IIS/7.0
Date: Fri, 25 Sep 2009 02:57:36 GMT
Content-Length: 222
<code class="language-json">
{
   "Request": "https://api.trademe.co.nz/v1/Listings/1.json",
   "ErrorDescription": "Listing id 1 is not valid",
   "Error": {
      "Code": "ListingNotFound",
      "UserDescription": "The listing you requested was not found.",
      "DeveloperDescription": "The listing requested was not found. This is because the listing id is incorrect.",
      "ErrorData": [
         {
            "Name": "ListingId",
            "Value": "1"
         }
      ]
   }
}
</code>