Developers
Rate limits and headers
Per-key, per-account and per-IP limits, the RateLimit and Retry-After headers, and how to back off.
On this page
Rate limits keep the API fast and fair for everyone. Each request counts against several limits at once, and the tightest one decides.
The limits#
| Limit | Requests per minute |
|---|---|
| Per key, free accounts | 30 |
| Per key, accounts with packs (coming with plans) | 120 |
| Per key, Pro and Studio plans (coming with plans) | 600 |
| Per account, all keys together | 2 × the per-key limit |
| Per IP address | 300 |
GET /v1/health, per IP | 60 |
Every account is on the free API tier until plans launch. A key can have its own lower limit (see per-key limits), but never a higher one. Limits count requests in one-minute windows that start with your first request.
Rate limit headers#
Every authenticated response tells you where you stand, for the tightest of your limits:
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: 01JD3YH2W4Y6A8C0E2G4J6L8N0
RateLimit-Limit: 30
RateLimit-Remaining: 27
RateLimit-Reset: 41
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests allowed in the window. |
RateLimit-Remaining | Requests left in this window. |
RateLimit-Reset | Seconds until the window resets. |
X-RateLimit-Limit, X-RateLimit-Remaining | The same values, under the older names many tools read. |
Retry-After | Only on a 429: seconds to wait before you try again. |
When you hit a limit#
You get 429 Too Many Requests with the rate_limited code:
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 18
RateLimit-Limit: 30
RateLimit-Remaining: 0
RateLimit-Reset: 18
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1794908338
{
"type": "https://studio.mutexai.net/docs/api/errors#rate_limited",
"title": "Too Many Requests",
"status": 429,
"detail": "Too many requests. Wait for the time in Retry-After, then try again.",
"code": "rate_limited",
"request_id": "01JD3YJ8Z0B2D4F6H8K0M2P4R6"
}
Wait for Retry-After seconds, then retry. A request that got a 429 did nothing, so it is safe to send again.
Retry with backoff#
Retry 429 and 5xx responses. Use Retry-After when it is there, and otherwise wait longer after each try, with some randomness so many clients do not retry at the same moment. Do not retry other 4xx errors: fix the request instead.
// Retries 429 and 5xx responses, waiting for Retry-After (or an exponential backoff with jitter).
export async function studioFetch(url, options = {}, attempts = 5) {
for (let attempt = 1; ; attempt++) {
const response = await fetch(url, options);
const retryable = response.status === 429 || response.status >= 500;
if (!retryable || attempt === attempts) {
return response;
}
const retryAfter = Number(response.headers.get('Retry-After'));
const wait = Number.isFinite(retryAfter) && retryAfter > 0
? retryAfter * 1000
: Math.min(30_000, 500 * 2 ** attempt) * (0.5 + Math.random() / 2);
await new Promise((resolve) => setTimeout(resolve, wait));
}
}
<?php
/**
* Sends a request with retries on 429 and 5xx, waiting for Retry-After (or an exponential
* backoff with jitter). $send performs one attempt and returns [status, headers, body].
*
* @param callable(): array{0: int, 1: array<string, string>, 2: string} $send
* @return array{0: int, 1: array<string, string>, 2: string}
*/
function studioWithRetries(callable $send, int $attempts = 5): array
{
for ($attempt = 1; ; $attempt++) {
[$status, $headers, $body] = $send();
$retryable = $status === 429 || $status >= 500;
if (! $retryable || $attempt === $attempts) {
return [$status, $headers, $body];
}
$retryAfter = (int) ($headers['retry-after'] ?? 0);
$waitMs = $retryAfter > 0 ? $retryAfter * 1000 : (int) (min(30_000, 500 * 2 ** $attempt) * (0.5 + mt_rand() / mt_getrandmax() / 2));
usleep($waitMs * 1000);
}
}
For POST and DELETE retries, always send the same Idempotency-Key.
Stay under the limits#
- Use webhooks instead of polling.
- Ask for up to 100 items per page when you list things.
- Cache your balance for a few seconds instead of reading it before every call.
Still stuck? Email [email protected] with what you tried and, for API problems, the request_id.