Rate limits and quota

Every key has the same limits. They cost nothing and calls are not billed; see Pricing. Over a rate limit the answer is 429 RATE_LIMITED with a Retry-After header in seconds.

Rate limitsCopy Anchor Link

From the tightest:

1. Per IP, before auth. 600 requests per minute per client IP, enforced before the Authorization header is parsed. It applies even to requests with no key.
2. Per key burst. 600 requests per minute per key. The limit is the same for every key and cannot be raised.
3. Per business burst. An organization key that selects a business with the Shyni-Business header also draws on a bucket of 600 requests per minute shared by all keys of the organization for that business, so one client's traffic cannot use up another's.
4. Booking limits on POST /orders. Creating a booking has two budgets:
   • 10 bookings per hour per IP, shared with the business's public booking page.
   • 60 bookings per hour per business, counted for the API separately from the booking page. API traffic cannot use up the page's bookings, and the page cannot use up the API's.

For a publishable key the IP is the visitor's. A secret key runs on your server, so send the end customer's address in the optional Shyni-Customer-IP header (IPv4 or IPv6; anything else is 400 INVALID_INPUT) and both budgets apply to that address. Without it a secret key is limited by its burst limit only. The header is ignored with a publishable key and on every other endpoint.

Pending orders capCopy Anchor Link

A publishable key at a business that confirms orders manually can have at most 10 unconfirmed orders from the API at once. The 11th POST /orders is 429 PENDING_ORDERS_LIMIT. Secret keys and businesses that confirm orders automatically have no cap. Nothing clears it on a timer: the business confirms or cancels pending orders, then you retry later.

QuotaCopy Anchor Link

Quota meters secret keys only.

• A publishable key is not metered. It has no monthly quota and its responses carry no quota headers.
• A secret key has a monthly quota of 150,000 requests per UTC calendar month. For a studio key the quota is shared by the studio's secret keys. For an organization key it is shared by all secret keys of the organization, across its businesses; the organization-level GET /me is not counted. Only successful calls count: a 2xx or 3xx is counted, a 4xx or 5xx and a preflight OPTIONS never are. At or over the quota a request is refused with 429 QUOTA_EXCEEDED and is not counted. The quota resets at 00:00 UTC on the 1st, and Retry-After points there.

Responses to secret-key requests, including 429 QUOTA_EXCEEDED, carry:

The headers are written before the body, so a call that ends 4xx or 5xx reads one higher than the stored counter. GET /me shows the stored figures; see Who am I.

Handling a 429Copy Anchor Link

if (res.status === 429) {
  const wait = Number(res.headers.get("Retry-After")); // seconds
  const { code } = await res.json(); // RATE_LIMITED, QUOTA_EXCEEDED or PENDING_ORDERS_LIMIT
}

RATE_LIMITED clears after the wait. QUOTA_EXCEEDED waits for the next UTC month, so reduce calls instead of looping. PENDING_ORDERS_LIMIT waits for the business to act on its pending orders. See Errors.