Rate limits

The limit#

Every connection may make 120 requests per minute. The limit applies per connection, meaning per restaurant: an app with many restaurants has its own quota for each. The window is 60 seconds long and starts with the first request. GET /me names the limit under rate_limit.

Polling orders every ten seconds and reporting statuses in between never comes close.

Headers#

HTTP/1.1 200 OK
RateLimit-Limit: 120
RateLimit-Remaining: 3
RateLimit-Reset: 17

Backing off#

On 429 rate_limited, wait Retry-After seconds and send the same request again. If RateLimit-Remaining is 0, wait for RateLimit-Reset before the next request. Track the wait per connection, not for your whole app.

// One queue per connection: the limit counts per connection (= per restaurant).
const pausedUntil = new Map(); // connection id → time

export async function send(conn, request) {
  const wait = (pausedUntil.get(conn.id) ?? 0) - Date.now();
  if (wait > 0) await new Promise((r) => setTimeout(r, wait));
  const res = await request();
  const remaining = Number(res.headers.get("ratelimit-remaining"));
  const reset = Number(res.headers.get("ratelimit-reset"));
  if (res.status === 429) {
    pausedUntil.set(conn.id, Date.now() + Number(res.headers.get("retry-after") ?? 1) * 1000);
    return send(conn, request); // the same request again, after the pause
  }
  if (remaining === 0 && reset > 0) pausedUntil.set(conn.id, Date.now() + reset * 1000);
  return res;
}

Saving requests#

• Webhooks or GET /events instead of constant polling.
• updated_since instead of fetching the whole list again.
• PUT /menu and POST /menu/availability (up to 500 entries) instead of hundreds of single PATCH calls.
• Read the menu once and then follow the menu.* events.

Failed authentication#

Requests with a token Flavoso does not know, or without one, are also counted per IP address. If more than 30 per minute come from one address, Flavoso answers 429 instead of 401. An expired or revoked token of yours does not count: it always gets 401, so you can refresh it, even for many restaurants at once. If you serve many restaurants from one server, mark a connection as disconnected as soon as a 401 is followed by invalid_grant on the refresh, instead of trying again and again.

The token endpoint has its own limits; there the answer is 429 temporarily_unavailable with Retry-After.