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 limit | Quota limit | |
|---|---|---|
| Caps | How many requests you send in a short time window | How much you use in total or per month, for example how many tracks you upload |
| Set by | Cyanite, and can depend on your agreement | Your agreement |
| When exceeded | 429 with problem title RateLimitExceeded | 403 with problem title QuotaMonthlyLimitExceeded or QuotaTotalLimitExceeded |
| Headers | retry-after, x-ratelimit-* | x-quotalimit-* |
| Resets | When the time window has passed, as told by retry-after | Once a month for a monthly quota, never for a total quota |
| What counts | Every request, including failed and rate-limited ones | Every authorized request of a type that has a quota, even if it fails later |
| Your reaction | Wait, then retry | Stop. 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:
| Header | Content |
|---|---|
retry-after | Seconds to wait before retrying. |
x-ratelimit-limit | Requests allowed in the current window. |
x-ratelimit-remaining | Requests left in the current window. |
x-ratelimit-reset | Unix 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-afterseconds. Add a little random jitter, so that parallel workers don't retry at the same moment. - Reschedule long waits.
retry-aftercan 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
429responses 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:
| Header | Content |
|---|---|
x-quotalimit-limit | The quota of the current period. |
x-quotalimit-remaining | The quota left in the current period. |
x-quotalimit-reset | Unix 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
- Understanding Webhooks: how notifications are delivered.
- API Reference: the
429and403problem types.