Rate limits

Every brand answers a fixed number of requests a minute per caller, meaning per token or per IP address. The number comes from the plan of the brand being read, not the plan of whoever is reading it. Past it the answer is 429 and says how long to wait.

The allowance

The allowance follows the plan of the account that owns the brand, because the manual is the thing being paid for. A brand sees its own numbers on its API page in the dashboard, in the account menu.

How calls are counted

• Per token, or per IP address when no token is sent. Builds sharing one token share one allowance.
• Per brand. Reading two brands from one IP address spends two allowances, one each, rather than one across both.
• In whole minutes. The count starts again at the top of each minute; it does not slide.
• A 304 counts. Sending the ETag back saves bandwidth and time, not requests. See Caching.
• A 401, 403, 404 or 410 is refused before the call is counted and carries none of the headers below.
• PDF renders are counted on their own, with the smaller number in the table, on top of the request the .pdf call spends. A 304, or a document served from the recent cache, spends the request and not a render. See PDF.

The headers to read

Every 200, 304 and 429 carries them. On a .pdf answer the three counts describe the request allowance; only a 429 for too many renders carries the render numbers instead. All four are exposed to a browser through CORS, so a page can read them from a fetch response.

Handling a 429

The body is JSON with one field, error, reading Too many requests. Up to N a minute. or, for the render counter, Too many PDF renders. Up to N a minute. Read Retry-After, wait that many seconds, try again, and give up after a few attempts rather than forever. A fixed sleep is a guess; the number in the header is the answer.

# curl waits for the seconds in Retry-After before each retry
curl -sS --retry 3 --retry-max-time 180 \
  https://stylehub.cloud/api/v1/manuals/acme.json

Raising the allowance

A higher plan for the brand's owner answers more often, for every caller of that brand. Plans are changed under Billing in the dashboard; the numbers are on the pricing page (opens in a new tab).