API Rate Limits and Quotas in Moonshadow

Moonshadow enforces 1,000 requests per minute per workspace. Learn how rate limits work, how to read the headers, and how to handle 429 responses.

Moonshadow enforces rate limits per workspace to ensure stable performance for all customers. If your integration sends a high volume of requests, monitor the rate limit headers and implement backoff to avoid disruptions.

Rate Limit Overview

The default limit is 1,000 requests per minute per workspace. This applies across all API keys and integrations within a single workspace. Burst traffic that exceeds this limit is throttled. After exceeding the limit, your requests will receive a 429 Too Many Requests response until the counter resets.

Rate Limit Headers

Every API response includes headers that show your current rate limit status:

X-RateLimit-Limit · integer · required

The maximum number of requests allowed per minute for this workspace. Default is 1,000.

X-RateLimit-Remaining · integer · required

The number of requests remaining in the current minute window.

X-RateLimit-Reset · integer · required

A Unix timestamp indicating when the rate limit window resets and your quota is fully restored.

Example Response Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1755373200
Content-Type: application/json

Reading Rate Limit Headers

You can read these headers after any API call to decide whether to pace your requests:

const res = await fetch('https://api.moonshadow.dev/v1/workspaces', {
  headers: { Authorization: 'Bearer msh_api_...' }
});

const limit = parseInt(res.headers.get('X-RateLimit-Limit'), 10);
const remaining = parseInt(res.headers.get('X-RateLimit-Remaining'), 10);
const reset = parseInt(res.headers.get('X-RateLimit-Reset'), 10);

console.log(`Remaining: ${remaining}/${limit}, resets at ${new Date(reset * 1000)}`);

Handling 429 Responses

If you exceed the limit, Moonshadow responds with 429 Too Many Requests and includes a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 45
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again later.",
    "request_id": "req_9g3b2c4d5e6f7h8i"
  }
}

Use exponential backoff with a jitter to retry safely:

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function fetchWithBackoff(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, options);

    if (res.status !== 429) {
      return res;
    }

    const retryAfter = res.headers.get('Retry-After');
    const delay = retryAfter
      ? parseInt(retryAfter, 10) * 1000
      : Math.min(1000 * Math.pow(2, attempt), 60000);

    const jitter = Math.floor(Math.random() * 500);
    await sleep(delay + jitter);
  }

  throw new Error('Rate limit retries exhausted');
}

Burst Limits and Best Practices

While the sustained limit is 1,000 requests per minute, short bursts above this threshold may still trigger throttling depending on traffic patterns. To stay within limits:

• Batch operations where possible instead of sending many individual requests.
• Cache responses for configuration and metadata that change infrequently.
• Use webhooks to receive updates instead of polling the API.
• Queue outgoing requests and pace them evenly across the minute window.

For questions about raising limits for high-volume workloads, contact support.