Skip to main content

​
Limits

Each limit uses a fixed window of 60 seconds. A window starts with the first request and ends 60 seconds later. The next request after that starts a new window. The limit per IP address is checked first. It counts every GET and HEAD request to an endpoint from that address, including requests without a valid key. If you use several keys from the same address, for example from one server or behind a shared outgoing address, they share this budget. IPv4 addresses are counted one by one. IPv6 addresses are counted per /64 network. The limit per key is checked after the limit per IP address, the length of the query string and the form of the key. A request that gets this far counts against the limit per key, also when it then fails with 400, 401, 404 or 500. See the order of checks in Errors. Other limits that apply to requests:
  • The query string is at most 1024 characters, including the leading ?. A longer one returns 400.
  • The Authorization header is not evaluated if it is longer than 256 characters. The request returns 401.
  • A cursor is at most 512 characters. A longer one returns 400.

​
Response headers

Once the limit per key has been checked, every response carries these headers. They refer to the limit per key. The headers are missing on responses that are sent before the key is read:
  • 429 from the limit per IP address.
  • 400 for a query string that is too long.
  • 401 for a missing key or a key of the wrong form.
  • 404 for a path that does not exist.
  • 405 and the answer to OPTIONS.

​
When you are limited

A request over a limit returns 429 with this body:
These are the headers of a 429 from the limit per key. The value 23 is an example:
Retry-After is the number of seconds until the window ends. Wait that long before the next request. It is present for both limits. When the limit per key is reached, the response also carries the three RateLimit-* headers. When the limit per IP address is reached, it does not.

​
Practical guidance

  • Read RateLimit-Remaining. When it is 0, the next request in the same window returns 429. Wait the number of seconds in RateLimit-Reset.
  • After a 429, wait the number of seconds in Retry-After, then retry.
  • Use the largest page size that fits your use. limit goes up to 100 for offers and 200 for events, so you need fewer requests. See Pagination.
Example that prints the headers of a response: