Quotas and spike arrests
The Sonos Control API limits the number of requests your integration can send to help ensure a pleasant listening experience for everyone. These limits apply to requests sent through the Sonos cloud. They do not apply to the LAN API.
As your user base grows, your integration may send more requests. Sonos applies some limits per app and others per user:
- Per app: All requests you send with your Client ID, across all your users.
- Per user: Requests you send with your Client ID for one Sonos user who authorized your integration (Client ID + user ID). Sonos counts requests per user, not per household.
Quotas
Quotas limit sustained request volume:
| Quota | Counted by | Limit |
|---|---|---|
| Per app | Client ID | 1,000 requests per minute |
| Per user | Client ID + user ID | 600 requests per minute |
| Per user | Client ID + user ID | 20,000 requests per day |
The per-app quota supports our largest partner integrations. If your integration regularly exceeds it, use a subscribe/eventing model instead of polling. See Subscribe documentation for more information.
Important: Subscribe and resubscribe requests count toward your quotas.
Each quota has its own counter. A single request counts toward every quota that applies to it.
Per-minute quotas
If your integration exceeds a per-minute quota, the request fails with an HTTP 429 Too Many Requests status. The response header contains retry information.
For a per-app quota violation, the response looks like this:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Content-Length: 82
Connection: keep-alive
RateLimit-Limit: 1000
RateLimit-Remaining: 0
RateLimit-Reset: 32
Retry-After: 32
{
"error": "Quota violation.",
"allowed quota": "1000 per minute per client"
}RateLimit-Reset and Retry-After use seconds.
For a per-user quota violation, the response body looks like this:
{
"error": "Quota violation.",
"allowed quota": "600 per minute per user"
}Daily quota
The daily quota uses a fixed window that resets at 00:00 UTC. It is not a rolling 24-hour window.
If your integration exceeds the daily quota for a user, requests for that user fail. The response has HTTP status 429 Too Many Requests. The response does not include a Retry-After header. Stop sending requests for that user until the quota resets at 00:00 UTC. Requests for your other users aren't affected.
The response body looks like this:
{
"error": "Quota violation.",
"allowed quota": "20000 per day per user"
}Spike Arrests
Spike arrests provide short-term burst protection. They throttle sudden spikes based on requests per second:
| Spike arrest | Counted by | Limit |
|---|---|---|
| Per app | Client ID | 100 requests per second |
| Per user | Client ID + user ID | 40 requests per second |
If your integration exceeds a spike arrest limit, the request fails with an HTTP 429 Too Many Requests status.
The following example shows a per-user spike arrest response:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 0
{
"fault": {
"faultstring": "Spike arrest violation. Allowed rate : ...",
"detail": {
"errorcode": "policies.ratelimit.SpikeArrestViolation"
}
}
}Retry-After uses seconds.
The response includes a Retry-After header, but its value is likely to be 0. Don't rely on Retry-After for spike arrests. Use exponential backoff with jitter instead, starting at about one second.
Retrying requests
Follow the retry guidance for the quota or spike arrest that caused the failure. For other 429 responses, wait the number of seconds specified by Retry-After, if provided. Otherwise, use exponential backoff with jitter. Don't retry failed requests in a tight loop.
The Sonos Control API may also throttle requests during periods of unusually high platform-wide traffic. Handle these the same way.
If your integration regularly exceeds its quota or spike policy, we will ask you to make changes. If we give you ample time and violations continue, we reserve the right to restrict or revoke your access.
Updated about 1 month ago
