Errors

Always check the success field

Almost every error body has "success": false; account-level errors (HTTP 402) may use a different format.
Some errors are returned with HTTP status 200, so a 2xx status alone does not mean the request worked.

Turn off automatic redirects in your HTTP client, then handle every response in this order:

If the HTTP status is not 2xx, it is an error.

If the body has "success": false, it is an error, even with HTTP 200.

Otherwise the request succeeded.

Log the full response body of every error; it is what HQ Support needs to help you.

Business rule errors (HTTP 200, status code 410 in the body)

When a request is well formed but a business rule stops it, the API answers with HTTP 200 and "status_code": 410 in the body.
Examples are a booking that breaks one of the account's booking rules, or a delete of a record that other records still depend on, as in this response to DELETE /car-rental/rate-types/{id}:

{
  "success": false,
  "status_code": 410,
  "errors": {
    "id": ["This rate type can't be deleted because it has rates that depend on them"],
    "error_message": "This rate type can't be deleted because it has rates that depend on them"
  },
  "data": []
}

errors.error_message joins every message with line breaks, ready to show to a person.
Here 410 means "cannot be completed with these values"; it does not mean "Gone".

Authentication errors (HTTP 200 or 401)

An invalid tenant or user token also returns HTTP 200, with status_code 401 or 403 in the body and the message in errors.error_message.
See Authentication for every case.

Errors with a real HTTP status

These errors use the HTTP status and put the message in message.
The exception is a 403 for an action the user's role does not allow, which may put the message in errors instead.

422 - validation failed.
errors lists the messages per field.

{
  "success": false,
  "message": "422 Unprocessable Content",
  "errors": {
    "pick_up_date": ["The pick up date is required"],
    "all_errors": ["The pick up date is required"]
  },
  "status_code": 422,
  "data": []
}

Most validation errors also include errors.all_errors, an array whose single entry joins every message with line breaks; it is not a field name.
A record that cannot be saved returns 422 on some endpoints, with a message such as "Contact could not be created", and HTTP 200 with status_code 410 on others.

404 - record not found.
Reading an unknown ID returns 404 with "status_code": 404, and so does deleting one on most endpoints; the message text varies.
GET /fields/{dbcolumn} is the exception: an unknown field returns a real HTTP 410 "Field doesn't exists".
Deleting a vehicle blocked period or a reservation external charge returns success even when the ID does not exist.
Some update endpoints, such as contacts, rates, rate types, seasons and fines, do not return 404: an unknown or deleted ID creates a new record.
Before you update a record whose ID you stored earlier, make sure it still exists, and check the id in the response.

429 - rate limit exceeded.
Wait the number of seconds in the Retry-After header before you retry.
See Rate limits and idempotency.

{
  "success": false,
  "message": "Too Many Attempts.",
  "status_code": 429,
  "data": []
}

Status codes

HTTP status	Meaning	What to do
200 with `"success": false`	Business rule or authentication error	Read `errors.error_message`.
400	The `filters` parameter is not valid JSON	Fix the JSON. See Filtering and incremental sync.
401	The `Authorization` header is missing, or the user behind the token is disabled	See Authentication.
3xx	The account moved to another region or was deactivated	Do not follow the redirect; contact HQ Support.
402	The account is suspended or not available in this region	Contact HQ Support.
403	The user's role does not allow this action, and the message can read `Page not found`	Use a user with the right role.
404	Unknown path or record	Check the base URL, the path and the ID. Some updates create a record instead (see above).
405	The path exists, but not with this HTTP method	Use the method shown in the endpoint reference.
422	Validation failed, or the record could not be saved	Read `errors`.
429	Rate limit exceeded	Wait `Retry-After` seconds.
500	Unexpected error	Retry later. If it persists, contact HQ Support with the request time, endpoint and payload. If `message` is `You are not allowed to see this reservation`, do not retry: the user cannot access that reservation.

Always check the success field#

Business rule errors (HTTP 200, status code 410 in the body)#

Authentication errors (HTTP 200 or 401)#

Errors with a real HTTP status#

Status codes#

Always check the success field

Business rule errors (HTTP 200, status code 410 in the body)

Authentication errors (HTTP 200 or 401)

Errors with a real HTTP status

Status codes