Responses & errors

In general, responses follow common HTTP conventions as much as possible.

Code	Name	Explanation
200	OK	Everything went okay
201	Created	Returned when POSTing to create a new resource was successful
204	No Content	Returned by some update and delete endpoints; the body is empty
400	Bad Request	The request was malformed, e.g. the body is not valid JSON (missing parameters throw 422)
401	Unauthorized	Invalid credentials supplied
403	Forbidden	The credentials are valid, but the request is not allowed (see below)
404	Not Found	The entity or route does not exist
422	Unprocessable Entity	A POST data JSON key or alike is malformed or missing
500	Internal Server Error	If you encounter this, please get in touch - this should not happen

When is 403 returned?

A 403 Forbidden means the API key was accepted, but the request is not allowed. Common causes:

The key does not have access to the endpoint, e.g. calling an endpoint that requires the App API Key with the App Widget Key ("You are not allowed to do this - due to missing scopes!").
The feature is not included in your app's plan ("Your app (...) is on a plan (...) where the feature you are trying to use (...) is disabled.").
The app does not have an active subscription.
The app is in test mode and its API trial has expired.
The email address of the account making the request has not been verified.

Successful calls:

Successful requests that result in 200 response codes will have their data inside a key named "data":

json{
  "data": "Response data here"
}

Error messages:

Whenever an error occurs, the API will attempt to write the error message inside a key named "error":

json{
  "error": {
    "message": "Error message here",
    "status_code": 400
  }
}

A 404 Not Found for an entity that doesn't exist also includes the type of entity that was looked up:

json{
  "error": {
    "message": "Entity does not exist",
    "status_code": 404,
    "model": "Booking"
  }
}

If one or more fields fail validation, the response is a 422 and the key will be named "errors", with the messages for each field contained in an array:

json{
  "errors": {
    "first_name": [
      "The first name field is required."
    ],
    "email": [
      "The email field is required."
    ],
    "timezone": [
      "The timezone field is required."
    ]
  }
}

The exact shape can vary between endpoints, so always check the HTTP status code first. Some endpoints return "error" as a plain string instead of an object (e.g. {"error": "Your API trial has expired - ..."}), and a few return a list of messages next to an empty fields array (e.g. {"fields": [], "errors": ["..."]}).