B Bookare Helpbookare.app →

Developers · Start here

Errors, dates, languages and limits

How the API answers, the formats it uses, and the limits it applies.

Answers

Success: { "data": ... } with 200 (or 201 when something was created).

Error:

{ "error": { "code": "unprocessable", "message": "phone: not a valid number.", "field": "phone" } }

message is readable and safe to show to the user, in the request’s language. field names the field at fault; reason gives a machine-readable detail where useful (signup_required, gone, limit, full, capacity, minNights).

HTTP code When
400 bad_request Unknown or missing field, bad JSON, bad date or range
401 unauthorized Missing or invalid key or token; wrong sign-in code
403 forbidden Read-only key on a change; account waiting for approval; team account at customer sign-in
404 not_found No such endpoint or thing, or not available for this kind of venue
405 method_not_allowed Wrong method (see the Allow header)
409 conflict Full, taken, already booked, an unpaid pack already open
422 unprocessable A value is not acceptable
429 rate_limited Too many requests (see Retry-After)
500 server_error Our side; check the current state before retrying a change

Unknown fields are refused with 400, in the query string and in the body. A typo never passes silently.

Dates, times, money

  • Dates are YYYY-MM-DD, times HH:MM, both in the venue’s time zone: Europe/Athens.
  • Timestamps (starts_at, expires, joined) are ISO 8601 in UTC.
  • Money is euro, as a number: "price_eur": 59.9. Prices are as the venue set them.
  • Ids are opaque strings; do not parse them (class ids happen to contain a date, but treat them as opaque).

Languages

Send ?lang=el (or en, or any language the venue offers), or an Accept-Language header. Error messages and names the venue translated (classes, packs, services, units) come back in that language. Otherwise the venue’s default language is used.

Requests

  • GET and DELETE take their fields in the query string; lists are comma-separated (?member_ids=a,b).
  • POST, PUT and PATCH take a JSON object body (Content-Type: application/json).
  • Path parameters are ids: /admin/members/{member_id}.
  • PATCH changes only the fields you send.

Limits

Who Limit
API key 120 requests a minute per key
Public and customer reads 240 a minute per IP
Public and customer writes 30 a minute per IP
Guest bookings 10 an hour per IP and 5 an hour per email, per venue
Sign-in codes a few per email and per IP every 15 minutes
Imports 100 rows per call

On 429, wait for Retry-After seconds.

Retries

GET is always safe to retry. A change that timed out may have happened: check before repeating (for example GET /me/bookings before booking again). Imports are safe to repeat: rows carry your own external_id.

CORS

Open to all origins, so browser apps can call the public and customer endpoints directly. The admin API works from browsers too, technically, but an API key must never be in a browser.

Versions

This is v1. New fields and endpoints are added without a new version; existing fields keep their meaning. See the changelog.