Received 429 rate_limited

Received 429 rate_limited

Symptom

A request to the NovaVMS API returned HTTP 429 with body {"error": "rate_limited"}. Subsequent requests from the same token keep failing until the window resets.

Likely causes

1. Your client is making more requests per second than the token’s tier allows.
2. You are polling a list endpoint instead of subscribing to webhooks.
3. A bug is retrying immediately on failure without backoff, amplifying the load.

Fix

Read Retry-After and wait

Every 429 response includes a Retry-After header with the number of seconds until the token’s bucket refills.

curl -i https://api.novalien.com/events | head -20
# HTTP/2 429
# retry-after: 12
# x-ratelimit-limit: 60
# x-ratelimit-remaining: 0
# x-ratelimit-reset: 1714147800

Wait at least Retry-After seconds before retrying.

Implement exponential backoff

Do not retry immediately. On the first 429, wait Retry-After. On subsequent consecutive failures, double the wait with jitter:

async function withBackoff<T>(fn: () => Promise<Response>): Promise<T> {
  let attempt = 0;
  while (true) {
    const res = await fn();
    if (res.status !== 429) return res.json();
    const retryAfter = Number(res.headers.get("retry-after") ?? 1);
    const jitter = Math.random() * 0.3 * retryAfter;
    await new Promise(r => setTimeout(r, (retryAfter + jitter) * 1000 * 2 ** attempt));
    attempt = Math.min(attempt + 1, 5);
  }
}

Replace polling with cursor pagination or webhooks

If you are polling /events every few seconds, switch to:

• Webhooks for push delivery — see webhook setup.
• Cursor pagination if you need historical catch-up — pass ?cursor=<last_seen_id> instead of refetching the whole list.

Tip

Read X-RateLimit-Remaining on every response, not just the 429s. When it drops below 10, slow your request rate before you get throttled. Pre-emptive throttling is cheaper than recovering from a burst of 429s.

Verify

1. After applying backoff, your client runs for 10 minutes without a 429.
2. X-RateLimit-Remaining stays above zero across the window.
3. Your application logs show no “rate-limited, retrying” warnings during normal operation.

If none of this worked

• Confirm your token’s tier in the admin UI under Settings → API tokens.
• If you need a higher limit, contact support with your average and peak request rate.
• See also: API error code reference.