Skip to main content

Understanding Limits

Two kinds of limits protect the Cyanite REST API and your account: rate limits and quota limits. They answer different questions, are signaled with different status codes and need different reactions. This page explains both, so you can tell which one you've hit and what to do about it.


Rate limits vs. quota limits​

Rate limitQuota limit
CapsHow many requests you send in a short time windowHow much you use in total or per month, for example how many tracks you upload
Set byCyanite, and can depend on your agreementYour agreement
When exceeded429 with problem title RateLimitExceeded403 with problem title QuotaMonthlyLimitExceeded or QuotaTotalLimitExceeded
Headersretry-after, x-ratelimit-*x-quotalimit-*
ResetsWhen the time window has passed, as told by retry-afterOnce a month for a monthly quota, never for a total quota
What countsEvery request, including failed and rate-limited onesEvery authorized request of a type that has a quota, even if it fails later
Your reactionWait, then retryStop. Continue after the reset, or contact Cyanite to raise the quota

In short: a rate limit means "slow down", a quota limit means "used up".


Rate limits​

A rate limit caps how many requests you can send in a short time window. Once the window has passed, your requests are accepted again.

Which rate limits apply​

Rate limits protect the API as a whole, and some can be part of your agreement with Cyanite. They can differ per type of request, for example uploads, model output fetches or searches.

Cyanite doesn't publish the values of its rate limits, because they can change. Build your client to honor retry-after instead of assuming a fixed limit.

What counts​

Every request counts, including requests that fail, for example with 404. A request that's rejected because of a rate limit counts as well, so retrying immediately makes things worse.

Response and headers​

When you exceed a rate limit, the API responds with 429 and the problem title RateLimitExceeded:

HeaderContent
retry-afterSeconds to wait before retrying.
x-ratelimit-limitRequests allowed in the current window.
x-ratelimit-remainingRequests left in the current window.
x-ratelimit-resetUnix timestamp (seconds) when the window resets. Not always sent.

retry-after is part of every 429 response. Rely on it rather than on x-ratelimit-reset, which some rate limits don't send.

How to react​

  • Wait and retry. Wait for retry-after seconds. Add a little random jitter, so that parallel workers don't retry at the same moment.
  • Reschedule long waits. retry-after can be several minutes. If your code can't wait that long, retry the call later instead of waiting in place.
  • Spread out bulk work. Rate limits apply to all requests of your API key together. Run a small, fixed number of workers, and send their requests through one client that backs off. If you get 429 responses regularly, lower the number.

Quota limits​

A quota limit caps how much you can use, for example how many tracks you can upload. Quotas are part of your agreement with Cyanite and can differ per type of request. There are two kinds:

  • A monthly quota renews once a month.
  • A total quota doesn't renew.

What counts​

Every authorized request of a type that has a quota counts once, even if it fails afterwards, for example because the track doesn't exist. Requests rejected with 429 (rate limit) or 422 (invalid input) don't use up quota.

Response and headers​

When a quota is used up, the API responds with 403 and the problem title QuotaMonthlyLimitExceeded or QuotaTotalLimitExceeded:

HeaderContent
x-quotalimit-limitThe quota of the current period.
x-quotalimit-remainingThe quota left in the current period.
x-quotalimit-resetUnix timestamp (seconds) when a monthly quota resets.

Other 403 responses are authorization errors. Their detail explains the cause.

How to react​

  • Stop sending requests of that type. Retrying won't succeed before the quota resets, and every retry is a wasted request.
  • Monthly quota: pause the affected work until the time in x-quotalimit-reset, then continue.
  • Total quota: contact Cyanite to extend it.

Checking your usage​

Successful responses don't include any limit headers, and there's currently no endpoint that shows your usage. You learn about a limit only when you hit it. Ask your Cyanite contact for your current usage and the limits of your agreement.


Polling and webhooks​

Cyanite notifies your webhook when the analysis of a track is complete. That costs you no requests. Polling GET /v1/library-tracks/{id}/models until results appear costs one request per poll and track. Every poll counts towards your rate limits and, if your account has a quota on model output fetches, towards your quota limit.

Webhooks should therefore be your default. Occasional polling is fine as a fallback, for example to recover notifications you missed while your endpoint was down. Keep it to the tracks that are still waiting for results, as described in When deliveries keep failing.

The API doesn't expose an analysis status. While a track is being analyzed, GET /v1/library-tracks/{id}/models responds with 200 and an empty items list. Once the analysis is complete, it returns the requested model outputs.


Further reading​