Skip to the page

Developers · API v1

Authentication and errors

Modes

ModeUsed byHow
Noneevery published readno header
Publishable keyorders, bookings, holds, enquiries, reservationsAuthorization: Bearer mpk_<slug>_…
Secret keythe shop's own drafts and findingsmsk_<slug>_…; these routes are not open yet

A publishable key is meant to sit in a web page. It can only send requests the shop approves, and only from the origins the shop listed for its site. A key that is wrong, revoked or used from another origin answers the same not_found as an unknown route, so a key cannot be probed.

Origins

A GET without an Origin header is served. A browser request from an origin the site does not list answers not_found.

Idempotency

Every POST and DELETE carries an Idempotency-Key header: 8 to 128 of A–Z a–z 0–9 _ -. Sending the same key with the same body again returns the first answer and writes nothing. The same key with a different body answers idempotency_mismatch. Without the header the answer is idempotency_key_required.

Rate limits

Per address: 5 writes in 10 minutes and 120 reads a minute. Per key: 300 writes and 20,000 reads a day. A hold is limited per device, per address and per stylist and day. Over a limit the answer is rate_limited with Retry-After.

Errors

Every error has one body, its message fixed per code:

{ "error": { "code": "not_found", "message": "Not found.", "fields": [], "requestId": "…" } }

fields names the request fields that failed their contract, for invalid. The full table follows.

CodeStatusMessage
invalid400The request does not match its contract.
idempotency_key_required400Send an Idempotency-Key header with every POST and DELETE.
stale_notice400The notice or consent version is not the site's current one. Fetch the site and try again.
bot_check400The bot check did not pass.
unauthenticated401The signature does not match.
not_found404Not found.
slot_taken409That time was just taken. Pick another.
idempotency_mismatch409This Idempotency-Key was sent before with a different request.
gone410This route is retired.
payload_too_large413The body is over 4 KB.
unsupported_media_type415Send the body as JSON.
rate_limited429Too many requests. Try again after the Retry-After header.
hold_limit429Finish or release your other hold first.
intake_paused503The shop is not taking requests just now.
internal500Something went wrong on our side.