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.
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 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:
{
"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.