Rate Limits

Understand request limits and how to handle rate limiting.

Rate limits protect the API from abuse and ensure fair usage for all users.

Limits by Plan

Plan	Requests per Minute
Free	100
Hobby	500
Pro	2,000

Limits are applied per API key using a sliding window algorithm.

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

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

Handling Rate Limits

When you exceed the limit, you’ll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded"
  }
}

The response includes a Retry-After header indicating how long to wait:

Retry-After: 30

Implementation Example

JavaScript

async function uploadWithRetry(file, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('https://api.stashfyle.com/v1/upload', {
      method: 'POST',
      headers: { 'Authorization': 'Bearer sk_live_xxx' },
      body: file
    });

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Retrying in ${retryAfter}s...`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response.json();
  }

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

Best Practices

Monitor your remaining quota

Check X-RateLimit-Remaining to proactively slow down before hitting limits.

Use exponential backoff

Instead of retrying immediately, wait progressively longer between retries.

Batch operations when possible

Instead of many small requests, consider batching operations.

Cache responses

For read operations, cache responses to reduce API calls.

Use separate keys for different services

Each key has its own rate limit, so separate keys for different services won’t interfere.

Need Higher Limits?

If you’re consistently hitting rate limits, consider upgrading your plan:

	Free	Hobby ($9/mo)	Pro ($29/mo)
Requests/min	100	500	2,000

Upgrade your plan →