Skip to Content
Developers

Errors

The shape of every error, what each code means and what to do about it.

The shape

Every error answers JSON with one error object:

{
  "error": {
    "code": "invalid_request",
    "message": "limit must be a whole number from 1 to 100.",
    "param": "limit",
    "request_id": "req_3f9a1c2e5b7d4a68"
  }
}
FieldMeaning
codeA fixed word. Branch on this. A code keeps its meaning for all of v1.
messageOne English sentence for a person. The wording may change, so do not parse it.
paramThe query parameter or body field at fault. Only on some 400 answers.
request_idThe id of this request. Quote it when you ask WeerOm about it.

When the shop's booking engine refuses a write, message carries the engine's own sentence when it has one, such as "First and last name are required" or "Email is required". A booking page may show it to the customer.

Codes

Keys and requests

StatuscodeWhat happenedWhat to do
400invalid_requestA parameter or body field is malformed, missing, out of range or unknown to the endpoint, or the booking does not fit the shop's rules. param names the field when there is one.Fix the request. Sending it again unchanged gives the same answer.
401missing_keyNo key in Authorization: Bearer.Send the key.
401invalid_keyWeerOm knows no such key.Check the key.
401revoked_keyThe shop removed this key.Ask the shop for a new key.
403plan_requiredThe shop is not on the Premium plan.Ask the shop to move to Premium. The key works again from then on.
403key_not_allowedThis kind of key may not call this endpoint. A public key reading customers, or a read key making a booking.Use a key of the right kind. See Authentication.
404not_foundNo object with this id, or no such endpoint. On a write, the service or the staff member is gone or inactive.Check the id and the path. A payment's id is its booking's id, and an unpaid booking has no payment.
429rate_limitedToo many requests.Wait the seconds in Retry-After, then send it again. See Rate limits.
500internal_errorSomething broke on WeerOm's side.Retry after a few seconds. If it keeps happening, send WeerOm the request_id.

Bookings and customers

StatuscodeWhat happenedWhat to do
403not_allowedThe shop does not allow this, for example a booking for a customer the shop blocked.Do not retry. Send the customer to the shop.
409slot_takenThe time is no longer free. Someone else booked it, or the shop changed its hours.Ask GET /availability again and pick another time.
409too_lateIt is past the shop's cut-off for cancelling or moving online.Tell the customer to call the shop. A write key may send "as": "staff" to act as the shop.
409wrong_stateThe booking is no longer open: it is cancelled, done or marked as a no-show.Read the booking again with GET /bookings/{id} and show its status.
429limit_reachedToo many bookings from one address or for one person in a short time, or the customer holds as many open bookings as the shop allows.Do not retry in a loop. Wait the seconds in Retry-After when the answer has it, or tell the customer to call the shop.
503bookings_pausedThe shop paused online booking.Try again later, or show the shop's phone number. A write key with "as": "staff" still books.

Retries

StatuscodeWhat happenedWhat to do
409idempotency_mismatchThis Idempotency-Key was used for a different request.Make a new key for a new request.
409request_in_progressThe first request with this Idempotency-Key still runs.Wait a second and send the same request again.

Safe retries explains both.

A parameter or body field the endpoint does not have answers 400 too. GET /payments?paid_afer=... fails with param: "paid_afer" instead of quietly returning every payment.

What to retry

AnswerRetry
400, 401, 403, 404No. The answer will not change until the request or the shop changes.
409 slot_takenNot the same request. Ask for the free times again and book another one.
409 too_late, wrong_state, idempotency_mismatchNo.
409 request_in_progressYes, with the same Idempotency-Key, after a second.
429After Retry-After seconds. For limit_reached without that header, not in a loop.
500Yes, a few times, with a growing wait: 2, 4, then 8 seconds. Send an Idempotency-Key with every POST and PATCH, so a retry cannot do it twice.
503 bookings_pausedNot until the shop opens online booking again.

Request ids

Every answer carries an X-Request-Id header, errors and successes alike. On an error, request_id in the body holds the same value.

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_3f9a1c2e5b7d4a68
Cache-Control: no-store

Log it beside every failed request. With the id, WeerOm can find the request in its logs.

On this page