MuviaDevelopers
Guides: Rate limits

Rate limits

Two fixed-window limits apply to every authenticated request:

Window Counted per Default limit
1 minute API key 120 requests
1 day Company — all its keys together 100,000 requests

The limits are counted per key and per company, never per IP address. The windows are fixed, not sliding: a window's count starts over when it ends. The values above are the defaults, which an installation can change, so drive your behaviour from the response headers rather than from this table.

Headers on every response

Every response, success or error, carries the state of the per-key minute window:

Header Meaning
X-RateLimit-Limit The requests the window allows.
X-RateLimit-Remaining The requests left in it.
X-RateLimit-Reset Seconds until the window resets.

GET /v1/whoami counts toward the per-key minute limit but not toward the company's daily budget; its limits object also tells the daily budget and how much of it the company has spent today. Each operation says in the OpenAPI document whether it counts (x-muvia-quota: counted or free-daily).

MCP

The MCP server limits each key too. Reads share the REST per-key per-minute limit (the same number); writes are limited to 30 per minute per key. A refused call answers with an error result: «This key made too many requests in a minute: try again in N seconds.» for reads, and «This key made too many changes in a minute: try again in N seconds.» for writes.

The 429 response

When a window is exhausted, the request answers 429:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit reached: 120 requests per minute per key",
    "status": 429,
    "hint": "Wait the number of seconds in the Retry-After header, then retry; X-RateLimit-Reset says when the window ends."
  }
}

with these headers:

Header Meaning
Retry-After Seconds until the window resets. Wait at least this long.
X-RateLimit-Limit The limit of the window that was exhausted.
X-RateLimit-Scope Which window it was: key or company.

Backing off correctly

  • Honour Retry-After: it is exact, not advisory. Retrying sooner only earns another 429.
  • Add jitter when several workers share a key, so they do not retry in lockstep.
  • Spread bulk work. 120 requests a minute is 2 a second per key; a nightly sync paced below that never meets the limit.
  • Read dataset rows in large pages (size up to 1000) rather than many small ones.
  • A company 429 means the daily budget is spent across all of the company's keys. Retrying will not help before Retry-After; coordinate with the company's other integrations. Issuing more keys does not raise it either.