Quotas & rate limits

SimplyFill enforces three kinds of limits: hourly rate limits (requests per hour), monthly quotas (PDFs generated and AI generations consumed), and feature limits (templates and API keys). Every limit is tier-based and visible from the dashboard.

This page is the operational reference. If you only want a price comparison, see Pricing.

Hourly rate limits

The rate limit is a sliding-window counter, measured per API key per hour. Every authenticated request increments the counter; the counter ticks back down as requests age out.

When the counter hits the limit, the next request returns 429 Too Many Requests with a Retry-After header naming the number of seconds until the oldest request ages out. Production-grade HTTP clients should honour Retry-After automatically — see the API errors reference for the retry policy contract.

Rate-limit headers are returned on every response, hit or miss:

Monthly PDF generation quotas

The PDF quota is a monthly counter that resets on the first of each calendar month at 00:00 UTC. Each successful POST /api/v1/generate/pdf (or its bulk equivalents) increments the counter by one per output PDF.

On PRO and BUSINESS the overage is metered through Stripe and billed at month-end. On FREE the 101st PDF returns 402 Payment Required and the dashboard surfaces an upgrade prompt.

Monthly AI generation quotas

The AI generation counter is independent from the PDF counter. AI generations cover automated mapping suggestions and template intelligence features — see Templates for what triggers an AI generation.

AI-quota exhaustion never blocks ordinary PDF generation. You'll see 402 Payment Required only when calling the AI endpoints themselves.

Feature limits

Two hard caps that don't reset monthly:

Templates per account

POST /api/v1/templates/upload returns 403 Forbidden when the cap is reached. Existing templates aren't affected — you keep generating, you just can't add a new one until you delete an old one or upgrade.

API keys per account

Spanning the cap across environments is your call — see Environments.

HTTP status codes

These are the exact codes the backend emits — see also API errors.

Warning thresholds

You won't be surprised by an outage. SimplyFill sends email notifications at three thresholds during the month:

The emails include the exact counts (824 / 1000 PDFs this month) and a one-click link to upgrade. If you've delegated billing to another team member, configure the notification recipient in Settings → Notifications.

Worked example: a FREE-tier account at 100%

You're on FREE. You've generated 100 PDFs this month. Here's what happens to call #101:

1. Your backend calls POST /api/v1/generate/pdf with a valid API key.

2. SimplyFill sees the request, validates the key, and increments the counter.

3. The counter hits 101 — past the FREE cap of 100.

4. The response is 402 Payment Required:

   {
     "error": "quota_exceeded",
     "message": "Monthly PDF quota exceeded for FREE tier.",
     "tier": "FREE",
     "limit": 100,
     "used": 100,
     "upgrade_url": "https://simplyfill.app/billing",
     "resets_at": "2026-06-01T00:00:00Z"
   }

5. The dashboard shows a red banner inviting an upgrade. Generation resumes immediately after the user picks a paid plan; no need to wait for month-end.

On PRO or BUSINESS the same sequence runs but step 4 returns 200 OK (the generation succeeds) and step 5 surfaces a yellow overage banner instead — you'll be billed $0.10 × overage (PRO) or $0.05 × overage (BUSINESS) at month-end.

Where these values come from

The backend app/config.py file is the single source of truth:

RATE_LIMIT_FREE: int = 100
RATE_LIMIT_PRO: int = 1000
RATE_LIMIT_BUSINESS: int = 10000
RATE_LIMIT_ENTERPRISE: int = 100000

QUOTA_PDF_FREE: int = 100
QUOTA_PDF_PRO: int = 1000
QUOTA_PDF_BUSINESS: int = 10000
QUOTA_PDF_ENTERPRISE: int = 999999  # unlimited

QUOTA_AI_FREE: int = 10
QUOTA_AI_PRO: int = 100

STRIPE_OVERAGE_PRICE_PRO: int = 10        # cents per PDF
STRIPE_OVERAGE_PRICE_BUSINESS: int = 5    # cents per PDF

If you're self-hosting (Enterprise), these are environment-overridable.

What's next

• Environments — per-environment quota counters
• Webhooks — usage events you can subscribe to
• Billing API — read your current quota state programmatically