Error Handling

Common error codes and meanings.

The API will use standard HTTP response codes where appropriate. That means that any 2xx code should be considered successful, 3xx a redirect, 4xx a validation or client-recoverable failure, and 5xx a server-side failure that may be temporary.

In the case of missing parameters, a 412 code with a message key is shown, mapped to a text message.

For POST requests, the 412 error code will be returned for validation errors with a field by field breakdown. If the errors element is present, it will be a json hash of fields to messages.

{
  "message": "This is the human readable summary of problems",
  "errors": {
    "password": [
      "is too short (minimum is 5 characters)"
    ]
  }
}

❗️

Code clients to classes of statuses (2xx), not to specific status codes (200)

If your client is handling errors, ensure that any 2xx response is considered successful, any 4xx response is considered a client correctable error, any 5xx response is considered a temporary server failure. Do not hardcode "200", "400", "500", etc as these codes may change.

Common Response Codes

Here's a table of common response codes. Generally, codes mean what they mean in the HTTP 1.1 RFC, so please refer there for any additional information.

CodeMeaning
200Resource was updated or created.
201Resource was created.
202Resource update is in progress. This likely means the update is asynchronous and may take some time to complete.
304Resource not modified. For clients that are compatible with ETags, indicates that the client should fetch the latest version of the resource from its cache. The server response will be empty.
400Parameters are missing or invalid.
401Unauthorized. Please log in and obtain a new authorization token.
404Resource not found.
406Could not complete request because it would violate some constraint. Example: can't delete listings that are not drafts.
429Rate limiting. Indicates that you should wait and try again in a while.