Skip to content
rare
⌘K
Marketplace API

Getting started

Rate limits

How many requests the rare.market API accepts per IP address and per API key, the 429 response, Retry-After and how to back off.

The API limits how fast each client can send requests. When you go over, it answers 429 rate_limited and tells you when to retry.

Limits

ClientPer minuteBurstPer day (UTC)
Anonymous (per IP address)606020,000
Free API key (per key, header x-api-key)300300200,000

Get a key at rare.market/developers: connect a Sui wallet and sign a message. No email.

The per-minute limit is a token bucket. A client starts with a full bucket (the burst) and it refills at the per-minute rate, one token a second for anonymous clients and five a second for a key. Most requests take one token. Some heavier reads take two or three: the API reference lists each operation's cost as x-cost. The daily count resets at 00:00 UTC.

Responses served from the edge cache do not reach the API and do not count (see Caching).

Event streams (/notify/stream) take one token to open, and each client can hold a few open at once: 3 per IP address, 10 per key. Opening one more answers 429 too_many_streams.

Spread polling over time instead of sending bursts on a timer. For live data, use a stream instead of polling (see Real-time notifications).

Response headers

Every response the API itself answers (not the edge cache) carries the client's limits:

HeaderValue
RateLimit-LimitRequests per minute for this client (60 or 300)
RateLimit-RemainingRequests left in the bucket right now
RateLimit-ResetSeconds until the bucket is full again
RateLimit-PolicyThe policy, e.g. 60;w=60;burst=60, 20000;w=86400
X-RateLimit-Day-RemainingRequests left today (UTC)
Retry-AfterOn 429 only: seconds to wait. For the daily limit, the seconds until 00:00 UTC

A response from the edge cache carries the headers of the request that filled the cache, so read RateLimit-Remaining as a guide, not a count.

When you are limited

Response
HTTP/2 429
content-type: application/json
retry-after: 1
ratelimit-limit: 60
ratelimit-remaining: 0
ratelimit-reset: 60
ratelimit-policy: 60;w=60;burst=60, 20000;w=86400

{"error":{"code":"rate_limited","message":"Too many requests. Try again in 1 s."}}

Wait at least Retry-After seconds, then retry. Refused requests do not use tokens, but retrying at once is refused again.

The gas sponsor routes under /sponsor have their own per-wallet and per-network limits. Those also answer 429, with the codes limit_reached, rate_limited or budget_exhausted. Waiting a second does not clear them. See Errors and Gas sponsoring.

Back off and retry

Retry on 429 and 503. Honour Retry-After when it is present; otherwise wait with exponential backoff and random jitter. Give up after a few attempts.

# curl retries 429 and 5xx responses and honours Retry-After (curl 7.66+).
curl --retry 5 --retry-max-time 60 \
  "https://rare.market/api/v1/collections/popkins"

Staying under the limit

  • Cache responses for as long as Cache-Control allows. See Caching.
  • Use limit up to 200 to fetch more rows per request. See Pagination.
  • Look up many items in one call with POST /items:lookup (up to 100 ids) instead of one request per item.
  • Use the event stream for live floors, listings and activity instead of polling.
--
TPS:--