Allowances
The two anonymous allowances are separate: a client that spends its read allowance can still submit, and the reverse.
How the API identifies a client
An anonymous client is its IP address as Multiliquid’s load balancer sees it.X-Forwarded-For entries that the caller sends are ignored. An IPv6 client is counted by its /64 network, so every address in that network shares one allowance. Systems that reach the API through one egress address, such as servers behind a shared NAT gateway, also share one allowance.
A credential gives a larger allowance
A request that sends anAuthorization credential, either a customer API key or a signed-in session token, is authenticated before it runs and is not counted against its IP address. It counts instead against 600 requests a minute for its user and 600 a minute for its organization. Every credentialed request from that user or organization shares these two allowances, including requests to the capital provider routes. An organization API key has no user, so its requests count against its organization’s allowance alone. If you need more than 300 anonymous requests a minute, use an API key. Authentication explains how to get one.
A key that lacks a route’s scope receives 403 with INSUFFICIENT_SCOPE. A credentialed POST /v1/submissions or POST /v1/redemptions with a key that lacks trade is rejected this way rather than accepted as an anonymous request.
A supplied credential never falls back to anonymous access. A credential that fails authentication receives 401, and a valid one without access receives 403. On the counted routes, each 401 for a supplied credential spends one of the client IP address’s 30 failed authentications a minute. Once they are spent, every request from that address to a counted route that carries a credential receives 429 before it is authenticated, until the window resets. The capital provider, organization, and delegate routes do not use this allowance.
Rate-limit headers
Every response to a counted request reports one allowance in three headers, computed when the response is written:- The response reports whichever allowance that counted or rejected the request has the fewest requests left, or on a tie the one that resets later.
- An anonymous request is counted by the allowance of its group, reads or writes.
- A credentialed request is counted by its user’s allowance once the credential identifies the user, so a
403or503after that point reports the user’s allowance. It is counted by its organization’s allowance once access is granted. A401also spends the client’s failed-authentication allowance. - A credential that is rejected before any allowance counts it reports the client’s failed-authentication allowance, which every credential is checked against.
- An allowance whose window has reset by the time the response is written reports all its requests and a full window, which the next request it counts starts.
- Routes that are not counted carry none of these headers. Neither does a request rejected before it is counted, such as one that sends a body with a
GET.
When the allowance is spent
A request over its allowance receives429 with code RATE_LIMITED. Retry-After gives the whole seconds until the window resets, and the allowance resets when Retry-After elapses. On a counted route RateLimit-Remaining is 0; the capital provider, organization, and delegate routes send no rate-limit headers.
A busy service
A429 whose RateLimit-Remaining is above 0 is not a rate-limit rejection, though it has the same code RATE_LIMITED: the service is busy. Swap quotes and builds, submissions, redemption preparations, and Solana batch order preparations wait up to 5 seconds for capacity before they answer this way. Redemption intake checks one new redemption at a time, so a redemption that arrives while another is being checked receives this 429 at once. The response still carries Retry-After, and its rate-limit headers show the requests the allowance has left.
Backing off
- On
429withRateLimit-Remaining: 0, or without rate-limit headers, the allowance is spent. Wait theRetry-Afterseconds before sending the request again. Retrying sooner is rejected again and does not shorten the wait. - On
429withRateLimit-Remainingabove0, the service is busy rather than the allowance spent. WaitRetry-Afterbefore retrying. - Pacing: if you send many requests, read
RateLimit-RemainingandRateLimit-Reset, and wait for the reset when the remaining count reaches zero instead of running into429. - On
503withRetry-After, wait that long. WithoutRetry-After, retry with exponential backoff and jitter, for example after about 1, 2, 4, and 8 seconds, up to a cap. Don’t retry a503with codeNETWORK_NOT_ACTIVE: the API does not serve the network. - On
401, fix the credential instead of retrying it. On the counted routes, repeated401responses spend the failed-authentication allowance and then block every credentialed request from the same IP address to those routes for the rest of the window. - Retries that change state: resending the same signed transactions to
POST /v1/submissions, or the same signed redemption toPOST /v1/redemptions, returns the existing records withreplayed: true, unless the redemption failed withfailure.resubmittable: true, which restarts it instead. Resubmitting the same batch order returnsDUPLICATE_ORDERwith itsorderId, so a retry after a timeout does not submit twice. After a408on any other request that changes state, read the current state before retrying. Retries and idempotency covers each route.
Counted routes
Write routes, 300 anonymous requests a minute per client:POST /v1/swap/build,POST /v1/swap/decode, andPOST /v1/submissionsPOST /v1/redemptionsandPOST /v1/redemptions/preparePOST /v1/batch-orders,POST /v1/batch-orders/prepare,POST /v1/batch-orders/{orderId}/cancel/prepare, andPOST /v1/batch-orders/{orderId}/cancel
GET and HEAD, 300 anonymous requests a minute per client:
/v1/info,/v1/info/evm, and/v1/info/svm/v1/networksand/v1/swap/pairs/v1/transactionsand/v1/volume/v1/swap/quote,/v1/submissions, and/v1/submissions/{submissionId}/v1/redemptionsand/v1/redemptions/{redemptionId}/v1/batch-orders/info,/v1/batch-orders, and/v1/batch-orders/{orderId}
GET /v1/submissions lists an organization’s submissions, so it requires a credential: an anonymous request spends its client’s read allowance and then receives 401.
Health, status, and documentation routes are not counted. The other routes that accept only a credential, the capital provider, organization, and delegate routes, are not counted against the anonymous or failed-authentication allowances and send no rate-limit headers, even on a 401 or 429. They count against the same 600-a-minute user and organization allowances without reporting them.
Related
Errors
The error body and every error code.
API introduction
API keys, test networks, and the interactive reference.