Rate-limit handling

WiseYield rate-limits API requests per user, sliding-window, scaled by subscription tier. This guide covers how to read the current state, what happens when you hit the limit, and how to back off correctly.

The limits

Tier	Requests / hour
Expired trial	3
Seed	25
Sprout	50
Trial / Harvest	100
Grove	200
Summit	1,000

The system fails closed — if the rate-limit backend is unreachable in production, requests are denied with 503 SERVICE_UNAVAILABLE rather than allowed through unmetered.

Headers on every response

Every response (success or 429) carries the current window state:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 2026-05-17T14:00:00.000Z

Header	Type	Meaning
`X-RateLimit-Limit`	integer	Total requests allowed in the current window
`X-RateLimit-Remaining`	integer	Requests remaining before the limit kicks in
`X-RateLimit-Reset`	ISO 8601 timestamp (UTC)	When the sliding window opens again

X-RateLimit-Reset is an ISO 8601 string, not a Unix timestamp. Parse with new Date(header) or datetime.fromisoformat(header.replace('Z', '+00:00')).

When you hit the limit

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-05-17T14:00:00.000Z
Retry-After: 1738
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED"
}

The Retry-After header is included as seconds-until-reset for clients that prefer the standard HTTP signal.

Backoff strategy

Wait until X-RateLimit-Reset before the next attempt. Exponential backoff with jitter is the right pattern for transient 5xx errors, but for 429 you have the exact reset time — use it.

async function fetchWithBackoff(url, init, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;

    const resetIso = res.headers.get('X-RateLimit-Reset');
    const waitMs = resetIso
      ? Math.max(0, new Date(resetIso).getTime() - Date.now())
      : 2 ** attempt * 1000;

    // Add jitter to avoid stampedes when many clients reset at the same time
    const jitter = Math.random() * 500;
    await new Promise(r => setTimeout(r, waitMs + jitter));
  }
  throw new Error('Max retries exceeded');
}

import time
import random
import requests
from datetime import datetime, timezone

def fetch_with_backoff(url, headers, max_retries=3):
    for attempt in range(max_retries):
        res = requests.get(url, headers=headers)
        if res.status_code != 429:
            return res

        reset_iso = res.headers.get('X-RateLimit-Reset')
        if reset_iso:
            reset = datetime.fromisoformat(reset_iso.replace('Z', '+00:00'))
            wait = max(0, (reset - datetime.now(timezone.utc)).total_seconds())
        else:
            wait = 2 ** attempt
        time.sleep(wait + random.uniform(0, 0.5))
    raise RuntimeError('Max retries exceeded')

Pre-flight checks

You don’t need to hit a 429 to know you’re close to the limit. Inspect X-RateLimit-Remaining on every response and throttle proactively:

const res = await fetch(url, init);
const remaining = parseInt(res.headers.get('X-RateLimit-Remaining') || '0', 10);
if (remaining < 5) {
  const resetIso = res.headers.get('X-RateLimit-Reset');
  const waitMs = Math.max(0, new Date(resetIso).getTime() - Date.now());
  console.warn(`Approaching rate limit, pausing ${waitMs}ms`);
  await new Promise(r => setTimeout(r, waitMs));
}

What the limits are NOT

Not per-key. Two keys owned by the same user share the same window. Splitting traffic across multiple keys does not multiply your budget.
Not per-endpoint. All requests count against the same per-user bucket, regardless of which route they hit.
Not per-IP. They’re scoped to the API key’s owning user.

Need a higher limit?

The standard tier limits are sized for typical integration patterns. If your application needs sustained throughput beyond Summit’s 1,000 req/hr, contact support@wiseyield.co — custom limits are available for enterprise integrations.

​The limits

​Headers on every response

​When you hit the limit

​Backoff strategy

​Pre-flight checks

​What the limits are NOT

​Need a higher limit?

​See also