Rate Limits

Understand API rate limits and how to handle them gracefully.

Overview

Shablonix API enforces rate limits to ensure fair usage and protect the service from abuse. Rate limits are applied per API key (or per user for JWT authentication) and vary by plan.

Three types of rate limits are enforced simultaneously:

Per-minute — Maximum requests allowed in a rolling 60-second window.
Per-day — Maximum requests allowed before midnight UTC.
Burst — Maximum requests allowed in a 10-second window, preventing sudden traffic spikes.

Rate Limit Tiers

Rate limits scale with your plan. Upgrade your plan to increase your limits.

Plan	Requests / Minute	Requests / Day	Burst (10s)
Trial	`30`	`1,000`	`50`
Starter	`60`	`5,000`	`100`
Pro	`300`	`50,000`	`500`
Business	`1,000`	`Unlimited`	`1,000`

Need Higher Limits?

If you need limits beyond the Business plan, contact our sales team for a custom Enterprise agreement.

Rate Limit Headers

Every authenticated API response includes rate limit headers so you can track your usage programmatically:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute for your plan.
`X-RateLimit-Remaining`	Number of requests remaining in the current minute window.
`X-RateLimit-Reset`	Unix timestamp (seconds) when the current minute window resets.

Example Response Headers

			
				HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 54
X-RateLimit-Reset: 1700000000

Rate Limit Exceeded

When you exceed any rate limit, the API responds with a 429 Too Many Requests status code along with a Retry-After header indicating how many seconds to wait.

429 Response json

			
				{
  "statusCode": 429,
  "message": "Rate limit exceeded (per-minute). Try again in 12s.",
  "error": "Too Many Requests",
  "retryAfter": 12
}

Respect Retry-After

Always check the Retry-After header before retrying. Continuously sending requests after receiving a 429 may result in longer cooldown periods.

Best Practices

Follow these guidelines to work efficiently within rate limits:

Exponential Backoff

When you receive a 429, wait for the Retry-After duration, then retry with exponential backoff (1s, 2s, 4s, 8s, ...).

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

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '1');
      const delay = retryAfter * 1000 * Math.pow(2, attempt);
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

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

Cache Responses

Cache API responses when possible to reduce the number of requests. Template metadata and generated documents that haven't changed can be served from cache.

Monitor Usage

Track the X-RateLimit-Remaining header in your application and proactively throttle requests as you approach the limit.

Batch Operations

Where possible, batch multiple operations into a single API call instead of making individual requests for each document.