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:

data, for table_refused
{
  "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.codeStatusWhat to do
app_key_invalid401The key is wrong, revoked or of another kind. Check it in the dashboard.
sdk_disabled403The SDK isn't switched on for this restaurant. Ask Tamr.
origin_not_allowed403A browser called from an origin the key doesn't list. Add the origin to the key.
session_expired401Start a new session with a fresh token or code, then send the call again once.
token_invalid401The diner token's signature, issuer, audience, key id or times are wrong. The message says which.
token_replayed409That token was already used. Sign a new one for each session.
code_invalid401The launch code is unknown, spent or expired. Mint a new one.
guest_not_allowed401The key has no guest mode: sign the diner in with a token or a code.
identity_required401Only 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_request400A field doesn't match the spec. The message says which.
not_found404Not this diner's, or doesn't exist. The two read the same on purpose.
menu_unavailable404No published menu is served at that branch and service mode.
message_rejected422The message was refused (too long, or not about the restaurant). Show the message.
nothing_heard422A voice note with no words in it. Ask the diner to try again.
rate_limited429Wait retryAfter seconds (also in the Retry-After header), then try again.
test_limit_reached429A test key's 50 conversations for the day are spent. Try again tomorrow, or use a live key.
max_turns_reached429The conversation is as long as it may be. Start a new one.
after_hours_closed503The location takes no conversations now. Show the message: the restaurant may have written it.
waiter_resting503The restaurant has paused its waiter. Show the message.
unavailable503Tamr can't serve this now. Try again later.
table_refused409A seat or a table order was refused. refusal says why.
pickup_refused409A pickup was refused. pickupRefusal says why.
pay_refused409A payment couldn't start. payRefusal says why.
review_refused409An order's dishes can't be rated. reviewRefusal says why: order_not_found, order_closed, too_old or nothing_to_review.
treat_refused409A treat can't be redeemed. treatRefusal says why: expired, withdrawn or already_redeemed. Charge the line as usual.
otheranyAnything 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

LimitLive keyTest key
Per app key, everything the app sends600 a minute60 a minute
One network address's share of a key200 a minute30 a minute
Guests' share of a key200 a minute20 a minute
Per guest device20 a minute20 a minute
Per signed-in diner, across their devices60 a minute60 a minute
Chat messages per diner20 a minute20 a minute
Conversations per dayNo limit50 per key
Server API, per secret key100 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.