# Errors

Source: https://developers.weerom.com/docs/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:

```json
{
  "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](https://developers.weerom.com/docs/authentication#three-kinds-of-key). |
| 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](https://developers.weerom.com/docs/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](https://developers.weerom.com/docs/idempotency) 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
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.
