Rate Limiting
The ZopNight API enforces per-organization rate limits at the gateway. Reference for limits, the 429 response, and best-practice backoff strategy.
The ZopNight API enforces rate limits per organization to ensure fair usage and service stability.
How It Works
Rate limiting is applied at the gateway level, tracked per organization using Redis. Limits are based on the number of requests per minute.
| Parameter | Value |
|---|---|
| Default limit | 100 requests per minute per organization (each deployment can set its own value) |
| Scope | Per organization (all users in an org share the limit) |
| Window | Fixed 1-minute window (resets on each clock minute boundary) |
| Per-endpoint variations | Every org-scoped endpoint shares the same bucket. The few exceptions are listed under Other limits. |
| Response headers | No X-RateLimit-* headers are returned. The per-org 429 has no Retry-After header either. Rely on the 429 response. |
| Auth endpoints | /auth/* is not rate limited. /oauth/* has its own per-IP limit: see Other limits. |
Rate Limit Response
When the rate limit is exceeded, the API returns a 429 status:
HTTP 429 Too Many Requests
{ "error": "rate limit exceeded"}Other limits
A few routes do not use the per-org bucket. Each has its own counter, on the same fixed 1-minute window.
| Route | Limit / min | Counted per |
|---|---|---|
/oauth/* | 30 | Caller IP |
/marketplace/resolve | 20 | Caller IP |
/marketplace/notifications | 120 | Caller IP |
Writes to /me/* and /my/* | 60 | User |
| MCP server calls | 100 | User |
The /oauth/* limit covers /oauth/authorize, /oauth/authorize/decision, /oauth/register,
/oauth/token and /oauth/revoke. The /me/* and /my/* limit covers writes to
/me/preferences, /me/profile, /my/preferences and /my/profile. Every MCP call counts, and a call over
the budget is refused, reads included.
The 429 bodies:
/oauth/*: the OAuthslow_downerror, see Error Handling./marketplace/*:{"error":"rate limit exceeded on /marketplace"}/me/*and/my/*:{"error":"rate limit exceeded"}- MCP:
{"error":"rate limit exceeded","code":"rate_limited"}
The /oauth/*, /marketplace/* and MCP 429s send a Retry-After header. Its value is the number of seconds until the current minute window ends (1 to 60).
Best Practices
- Honour
Retry-After: when a 429 carries this header, wait that many seconds before retrying. - Implement exponential backoff: when you receive a 429 response, wait before retrying. Double the wait time with each retry (1s, 2s, 4s, etc.).
- Cache responses: avoid redundant API calls by caching resource lists, schedules, and other data that changes infrequently.
- Use batch endpoints: fetch multiple resources with
/resources/by-idsinstead of individual GET requests. - Avoid polling: use reasonable intervals when polling for action status or refresh completion.