Rate Limits

Unmarkdown™ uses a sliding window rate limiter to ensure fair usage across all users. Rate limits are applied per user (not per API key).

Limits by Tier

Tier	Rate Limit
Free	10 requests per second
Pro	30 requests per second

Rate Limit Headers

Every API response includes rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per second
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp (seconds) when the window resets

Example response headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1739577601

Handling 429 Responses

When you exceed the rate limit, the API returns a 429 status code:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Limit: 10 req/sec",
    "status": 429
  }
}

The response includes the standard rate limit headers so you know when to retry.

Best Practices

Implement exponential backoff. When you receive a 429, wait before retrying. A simple strategy:

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

    if (res.status === 429) {
      const retryAfter = parseInt(res.headers.get('X-RateLimit-Reset') || '0');
      const waitMs = retryAfter > 0
        ? (retryAfter * 1000) - Date.now()
        : Math.pow(2, attempt) * 100;
      await new Promise(resolve => setTimeout(resolve, Math.max(waitMs, 100)));
      continue;
    }

    return res;
  }
  throw new Error('Max retries exceeded');
}

Batch your requests. Instead of publishing documents one at a time in a tight loop, space them out or use the Create and Publish endpoint to reduce total calls.

Monitor your remaining quota. Check the X-RateLimit-Remaining header to throttle your requests before hitting the limit.