Rate Limiting Guide

FiscalAPI uses a token bucket rate limiter to protect the platform and ensure fair usage. Limits are applied per account and scale with your subscription tier.

Tier-based limits

Your rate limit tier is determined by your subscription's merchant count:

Tier	Merchants	Requests/min	Burst
Sandbox	Test accounts	100	200
Starter	1 -- 10	1,000	2,000
Growth	11 -- 50	5,000	10,000
Enterprise	251+	20,000	40,000

The burst limit allows short spikes above the sustained rate. Tokens refill continuously at the per-minute rate.

How token bucket works

Each account has its own token bucket:

1. Tokens refill at a steady rate (requests per minute / 60 = tokens per second)
2. Unused tokens accumulate up to the burst limit
3. Each API request consumes one token
4. When the bucket is empty, requests are rejected with 429 Too Many Requests

This allows bursty traffic patterns (e.g., batch submissions) while enforcing a sustained average rate.

Response headers

Every authenticated API response includes rate limit headers:

Header	Description	Example
X-RateLimit-Limit	Maximum requests per minute for your tier	1000
X-RateLimit-Remaining	Tokens currently available	847
X-RateLimit-Reset	Unix timestamp when the next minute boundary resets	1710511260

When rate limited

A 429 response includes an additional header and error body:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710511260

{
  "error": "rate_limit_exceeded",
  "retry_after": 12
}

The Retry-After header indicates the number of seconds until the next minute boundary.

Best practices

• Monitor headers -- Check X-RateLimit-Remaining to anticipate limits before hitting them
• Implement backoff -- On 429 responses, wait for the Retry-After duration before retrying
• Batch when possible -- Use the batch endpoint for bulk transaction submission to reduce individual API calls
• Upgrade your tier -- If you consistently hit limits, increase your merchant count to access a higher tier (see Billing guide)

Tier upgrades

Your rate limit tier updates automatically when you change your merchant count via PATCH /v1/subscriptions. The new tier takes effect on the next API request -- no restart or delay required.