Rate limits & quotas

The StatusOwl REST API enforces two independent gates on every authenticated request:

1. A per-key request rate — fixed-window, measured per minute.
2. A per-organization quota — daily and monthly request caps shared across every key in the org.

A request that would breach either gate is rejected with 429 Too Many Requests. Both gates run on every successful response, and both expose their current state as response headers — your client can pace itself without waiting for a 429 to arrive.

Per-key rate limit

Each API key has a rate_limit_rpm (requests per minute). The default is 600 RPM when no override is set; Enterprise customers can request a custom limit. The window is fixed at 60 seconds, keyed by the API key — not by IP, and not by organization, so two keys in the same org each get their own budget.

Every successful response includes:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 60

• X-RateLimit-Limit — the RPM ceiling for this key.
• X-RateLimit-Remaining — requests left in the current minute.
• X-RateLimit-Reset — seconds until the window rolls over and Remaining resets to Limit.

When a key crosses its RPM, the API responds:

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{
  "error": "Rate limit exceeded",
  "limit_rpm": 600,
  "retry_after_seconds": 42
}

The Retry-After header value matches retry_after_seconds in the body — back off for that many seconds and retry. For long-running scrapers, the cleanest pattern is to read X-RateLimit-Remaining on every response and pause preemptively when it nears zero.

Per-organization daily and monthly quotas

Independent of the per-minute rate, every organization has a daily and monthly request cap that all keys in the org draw from. The defaults map to your plan; Enterprise customers can negotiate custom caps. Both counters reset automatically — daily at UTC midnight, monthly at the start of each calendar month.

Every successful response also includes the current quota state:

X-Quota-Daily-Limit: 100000
X-Quota-Daily-Remaining: 99873
X-Quota-Monthly-Limit: 3000000
X-Quota-Monthly-Remaining: 2987112

When the daily cap is hit:

HTTP/1.1 429 Too Many Requests

{
  "error": "Daily API quota exceeded",
  "limit": 100000,
  "resets_at": "2026-05-10T00:00:00.000Z"
}

When the monthly cap is hit:

{
  "error": "Monthly API quota exceeded",
  "limit": 3000000,
  "resets_at": "2026-06-01T00:00:00.000Z"
}

resets_at is the ISO-8601 timestamp of the next reset boundary. Use it to schedule a retry; there is no Retry-After header for quota 429s.

Backoff guidance

A robust client should:

1. Respect the response headers proactively. When X-RateLimit-Remaining drops below 10% of X-RateLimit-Limit, slow down for the next few seconds rather than racing to 0.
2. Honor Retry-After. On a rate-limit 429, sleep Retry-After seconds (or retry_after_seconds in the body) before the next attempt.
3. Stop retrying on a quota 429. A daily or monthly cap won't clear in seconds; surface the error to your caller and resume after resets_at.
4. Cap retry attempts. Even on rate-limit 429s, give up after a few attempts to avoid retry storms during incidents.

Plan defaults

Default rate-limit and quota allotments are part of each plan tier; the current values are documented on the pricing page. API access is available on Team and above — see API scopes & plan gating.

What the limits cover

The gates apply to all /v1 endpoints behind authentication. Public health endpoints (/healthz, /readyz) are unauthenticated and don't count.

See also

• API authentication — how to present the bearer token.
• Errors — the full status-code reference and envelope shape.
• Managing API keys — creating, rotating, and revoking keys; per-key custom RPM for Enterprise.