Rate limits
The read-only Network API has no rate limit of its own. Limits apply where a request costs something (sending transactions, MLX Node's worker routes and starting a checkout), and an over-limit request gets a 429.
How limits answer
An over-limit request gets 429 with the usual error body, and nothing is done:
{ "error": "Too many transactions. Wait a minute and try again." }There is no Retry-After header. Every limit counts in a window (most are one minute) and the next window starts fresh, so waiting out the window is always enough. Counters are per IP address, per wallet or per Mac, as each section says. The shared per-IP and per-wallet counters on POST /api/tx and the deposit routes let a request through if their store can't be reached, rather than refusing everyone.
Reads
The GET endpoints in Network API aren't rate limited by the app. Most of them are cached at the CDN for a few seconds, so polling faster than their Cache-Control allows returns the same answer. Poll at the pace the data changes: a block or a seat at most as often as blocks are sealed, live mining and World every several seconds, the open data files once a day.
Sending transactions: POST /api/tx
Six limits, checked in this order:
| Limit | Counted per | Refused with |
|---|---|---|
| 40 a minute | IP address, on each server instance | "Too many transactions. Wait a minute and try again." |
| 60 a minute | IP address, across the whole network | the same message |
| 30 a minute | wallet (the transaction's from) | "Too many transactions from this wallet. Wait a minute and try again." |
| 20 failed transactions in an hour | wallet | "Too many failed transactions from this wallet. Try again in an hour." |
10 new wallets (create_account) in an hour | IP address | "Too many new wallets from this network. Try again in an hour." |
| 25 new wallets in a UTC day | IP address | "Too many new wallets from this network today. Try again tomorrow." |
Linking Macs and buying MLX have limits of their own, answered with 409: see Fair use.
- Every request counts against the IP limits, including replays of a transaction already sealed and transactions that are refused.
- The failed-transaction limit counts transactions that were sealed with
status: "failed", the first time each was sent. It runs by clock hour (UTC): once a wallet reaches it, its transactions are refused until the next hour starts. - Transactions the protocol signs itself (
from: "sequencer") aren't counted per wallet.
An app that signs and sends on a person's behalf will rarely meet these. A script should send transactions one after another, waiting for each record, and stop when it sees failures. See Submitting.
MLX Node's routes: /api/worker/*
Each route counts the requests of each Mac (by its device key) per minute:
| Route | Limit |
|---|---|
POST /api/worker/job | 240 a minute |
POST /api/worker/result | 240 a minute, and no more than 300 results a minute per Mac counted across all server instances |
POST /api/worker/hello, /redeem, /feedback, POST /api/log/cosign | Lower per-minute limits, set per route |
Over the limit is 429 { "error": "Slow down" }; MLX Node treats it like a lost reply and asks for the next job. The route limits are counted on each server instance; the results limit is shared.
The worker routes also pace the work itself. These aren't errors:
- One job per 200 ms. A Mac that asks again sooner is held until the gap has passed, never refused.
- Free seats wait a random 1 to 9 seconds before each job is handed out, then get a short job. Dedicated seats get full jobs back to back. See Free seats.
- A result can't be faster than the job. A finished result that comes back sooner than 1 ms per token after the hand-out is refused with 409
"Too fast for this job", and that job is gone.
The whole exchange is on Worker protocol.
Checkout: POST /api/pay
Starting a crypto checkout (a seat or a deposit) is limited per IP address, per minute, on each server instance: 429 "Too many checkouts started. Wait a minute and try again."
Other limits
Two things on the site that aren't part of the developer API are limited too, per IP address: the visitor analytics beacon and the sign-up forms (Mac beta, Wombat Rewards). The admin sign-in locks out after repeated wrong passwords.