Rate Limiting

To protect the API from overload, the number of requests is limited per minute. The limit is computed using a sliding window.

Quotas

Bucket	Default limit	Scope
Default	60 requests / minute	Most endpoints
services_status_300rpm	300 requests / minute	GET /services/{id}/status (high-frequency polling)
services_changes_120rpm	120 requests / minute	Mutating endpoints (power, rebuild, upgrade, password)

Response Headers

Every response returns the current quota state:

Header	Meaning
X-RateLimit-Limit	Total quota per minute
X-RateLimit-Remaining	Remaining requests
X-RateLimit-Reset	Unix timestamp when the quota resets

Quota Exceeded (429)

When the quota is exceeded, 429 Too Many Requests is returned, and the Retry-After header tells you how many seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1785000000

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Request limit exceeded. Please try again later."
  },
  "meta": { "trace_id": "...", "timestamp": "..." }
}

Recommendations

• On 429, wait for the Retry-After duration and retry with exponential backoff.
• Instead of continuously polling service status, use Webhooks where possible — notifications arrive instantly and consume no quota.
• For bulk operations, spread requests over time; do not send hundreds of requests at once.