Skip to content
Theme
Upload a photo Upload
Theme
Theme
Upload a photo

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
  1. The limits
  2. Rate limit headers
  3. When you hit a limit
  4. Retry with backoff
  5. Stay under the limits

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#

LimitRequests per minute
Per key, free accounts30
Per key, accounts with packs (coming with plans)120
Per key, Pro and Studio plans (coming with plans)600
Per account, all keys together2 × the per-key limit
Per IP address300
GET /v1/health, per IP60

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:

Response headers
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
HeaderMeaning
RateLimit-LimitRequests allowed in the window.
RateLimit-RemainingRequests left in this window.
RateLimit-ResetSeconds until the window resets.
X-RateLimit-Limit, X-RateLimit-RemainingThe same values, under the older names many tools read.
Retry-AfterOnly 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:

429 Too Many Requests
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.

JavaScript
// 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
<?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.

Type at least 2 letters. Use the arrow keys to move and Enter to open.

    Type at least 2 letters. Use the arrow keys to move and Enter to open.