Responses and errors

The envelope

Every answer, success or failure, has the same four fields:

{ "isSuccess": true, "errorCode": 0, "message": "OK", "data": {} }

• isSuccess is true exactly when the HTTP status is below 400.
• errorCode is 0 on success; otherwise it says exactly what went wrong.
• message is always safe to show to a guest.
• data is the answer, or null on a failure.

A list is always data.items. Every answer carries an X-Request-Id header: quote it if you contact us.

Validation failures

A request with a mistake answers 400 with errorCode 1001, and data.fields names every field that is wrong:

{
  "isSuccess": false,
  "errorCode": 1001,
  "message": "Please check the highlighted fields",
  "data": { "fields": [{ "field": "guest.email", "message": "Invalid email address" }] }
}

Error codes

errorCode	HTTP	Name	What it means
0	200, 201	OK	It worked. data holds the answer.
1001	400	VALIDATION_ERROR	Something in the request is not right. data.fields names each field and why.
1002	400	INVALID_BODY	The body is not valid JSON.
2001	401	UNAUTHENTICATED	No key, or not a live one: check it, or create a new one in Settings → Developers.
2003	403	FORBIDDEN	The key may not do this from here: a publishable key from a website it does not list, a secret key from a browser, or a publishable key on a secret-only endpoint.
3001	404	NOT_FOUND	No such property, room or request in your workspace.
4001	409	CONFLICT	The Idempotency-Key was already used for a different booking request.
4002	409	DATES_UNAVAILABLE	Those dates are no longer available.
5001	429	RATE_LIMITED	Too many calls. Wait for the number of seconds in Retry-After, then try again.
9001	500	INTERNAL	Our fault. Try again later, and quote the X-Request-Id header if you contact us.

New codes may be added. Treat a code you do not know by its HTTP status.

Data types

• Ids are UUID strings.
• Dates are YYYY-MM-DD; a stay’s checkOut is the morning the guest leaves, so a stay from the 20th to the 23rd is three nights.
• Money is a decimal string, such as "120.00", always beside its currency (ISO 4217). Never a number, so it is never rounded.
• Boards are RO room only, BB bed and breakfast, HB half board, FB full board and AI all inclusive.

Versioning

Within v1 we only add: new endpoints, new optional fields, new error codes. Ignore fields you do not know. See the changelog.