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"
}
}| Field | Meaning |
|---|---|
code | A fixed word. Branch on this. A code keeps its meaning for all of v1. |
message | One English sentence for a person. The wording may change, so do not parse it. |
param | The query parameter or body field at fault. Only on some 400 answers. |
request_id | The 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
| Status | code | What happened | What to do |
|---|---|---|---|
| 400 | invalid_request | A 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. |
| 401 | missing_key | No key in Authorization: Bearer. | Send the key. |
| 401 | invalid_key | WeerOm knows no such key. | Check the key. |
| 401 | revoked_key | The shop removed this key. | Ask the shop for a new key. |
| 403 | plan_required | The shop is not on the Premium plan. | Ask the shop to move to Premium. The key works again from then on. |
| 403 | key_not_allowed | This 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. |
| 404 | not_found | No 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. |
| 429 | rate_limited | Too many requests. | Wait the seconds in Retry-After, then send it again. See Rate limits. |
| 500 | internal_error | Something broke on WeerOm's side. | Retry after a few seconds. If it keeps happening, send WeerOm the request_id. |
Bookings and customers
| Status | code | What happened | What to do |
|---|---|---|---|
| 403 | not_allowed | The shop does not allow this, for example a booking for a customer the shop blocked. | Do not retry. Send the customer to the shop. |
| 409 | slot_taken | The time is no longer free. Someone else booked it, or the shop changed its hours. | Ask GET /availability again and pick another time. |
| 409 | too_late | It 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. |
| 409 | wrong_state | The 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. |
| 429 | limit_reached | Too 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. |
| 503 | bookings_paused | The shop paused online booking. | Try again later, or show the shop's phone number. A write key with "as": "staff" still books. |
Retries
| Status | code | What happened | What to do |
|---|---|---|---|
| 409 | idempotency_mismatch | This Idempotency-Key was used for a different request. | Make a new key for a new request. |
| 409 | request_in_progress | The 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
| Answer | Retry |
|---|---|
| 400, 401, 403, 404 | No. The answer will not change until the request or the shop changes. |
409 slot_taken | Not the same request. Ask for the free times again and book another one. |
409 too_late, wrong_state, idempotency_mismatch | No. |
409 request_in_progress | Yes, with the same Idempotency-Key, after a second. |
| 429 | After Retry-After seconds. For limit_reached without that header, not in a loop. |
| 500 | Yes, 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_paused | Not 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-storeLog it beside every failed request. With the id, WeerOm can find the request in its logs.