# Errors and rate limits

> Every error code Tamr's API and SDK answer, what each means and what to do, plus the rate limits for live keys, test keys, guests and secret API keys.

Source: https://tamr.link/docs/errors

Every error from `/api/v1` has the same body: a top-level `defined`, `code` (such as `UNAUTHORIZED`), `status` and `message`, and a `data` object with the stable lower-case reason in `data.code` and the request's id in `data.requestId` (the [ClientApiError](https://tamr.link/docs/api/schemas#clientapierror) schema). Switch on `data.code`; `message` is for people and may change. Some codes carry more in `data`, such as why a table order was refused and which dishes:

data, for table_refused:

```json
{
  "code": "table_refused",
  "requestId": "req_01",
  "refusal": "unavailable",
  "problems": [
    {
      "dishId": "dish_kafta",
      "name": "Kafta skewers",
      "problem": "sold_out"
    }
  ]
}
```

Every response carries an `x-request-id` header. Give it to Tamr's support with the time.

## Error codes

| `data.code` | Status | What to do |
| --- | --- | --- |
| `app_key_invalid` | 401 | The key is wrong, revoked or of another kind. Check it in the dashboard. |
| `sdk_disabled` | 403 | The SDK isn't switched on for this restaurant. Ask Tamr. |
| `origin_not_allowed` | 403 | A browser called from an origin the key doesn't list. Add the origin to the key. |
| `session_expired` | 401 | Start a new session with a fresh token or code, then send the call again once. |
| `token_invalid` | 401 | The diner token's signature, issuer, audience, key id or times are wrong. The message says which. |
| `token_replayed` | 409 | That token was already used. Sign a new one for each session. |
| `code_invalid` | 401 | The launch code is unknown, spent or expired. Mint a new one. |
| `guest_not_allowed` | 401 | The key has no guest mode: sign the diner in with a token or a code. |
| `identity_required` | 401 | Only a signed-in diner's goal is kept. A guest's or a test key's session can't set one. Don't renew the session for it. |
| `invalid_request` | 400 | A field doesn't match the spec. The message says which. |
| `not_found` | 404 | Not this diner's, or doesn't exist. The two read the same on purpose. |
| `menu_unavailable` | 404 | No published menu is served at that branch and service mode. |
| `message_rejected` | 422 | The message was refused (too long, or not about the restaurant). Show the message. |
| `nothing_heard` | 422 | A voice note with no words in it. Ask the diner to try again. |
| `rate_limited` | 429 | Wait `retryAfter` seconds (also in the `Retry-After` header), then try again. |
| `test_limit_reached` | 429 | A test key's 50 conversations for the day are spent. Try again tomorrow, or use a live key. |
| `max_turns_reached` | 429 | The conversation is as long as it may be. Start a new one. |
| `after_hours_closed` | 503 | The location takes no conversations now. Show the message: the restaurant may have written it. |
| `waiter_resting` | 503 | The restaurant has paused its waiter. Show the message. |
| `unavailable` | 503 | Tamr can't serve this now. Try again later. |
| `table_refused` | 409 | A seat or a table order was refused. `refusal` says why. |
| `pickup_refused` | 409 | A pickup was refused. `pickupRefusal` says why. |
| `pay_refused` | 409 | A payment couldn't start. `payRefusal` says why. |
| `review_refused` | 409 | An order's dishes can't be rated. `reviewRefusal` says why: `order_not_found`, `order_closed`, `too_old` or `nothing_to_review`. |
| `treat_refused` | 409 | A treat can't be redeemed. `treatRefusal` says why: `expired`, `withdrawn` or `already_redeemed`. Charge the line as usual. |
| `other` | any | Anything else, including a code added after these docs. Read `message` and the status. |

A Server API call with no secret key, or one Tamr doesn't accept, answers 401; a key without the route's permission answers 403. Neither carries a code of its own, so both read as `other`: switch on the status.

## Rate limits

| Limit | Live key | Test key |
| --- | --- | --- |
| Per app key, everything the app sends | 600 a minute | 60 a minute |
| One network address's share of a key | 200 a minute | 30 a minute |
| Guests' share of a key | 200 a minute | 20 a minute |
| Per guest device | 20 a minute | 20 a minute |
| Per signed-in diner, across their devices | 60 a minute | 60 a minute |
| Chat messages per diner | 20 a minute | 20 a minute |
| Conversations per day | No limit | 50 per key |
| Server API, per secret key | 100 a minute | |

A refused call is 429 with `retryAfter` in seconds and a `Retry-After` header. One network address can use at most a third of a live key's budget, so a single machine holding your app's public key can't use up the budget your diners share. That share is generous on purpose: diners on the same restaurant Wi-Fi or mobile network share an address. Every other limit is per key, per diner or per device.
