Rate Limits & Quotas

Every request against /v1/pdf is checked against two independent limits. They fail differently on purpose — the error code tells you which one to handle, and how.

Rate limit

A short sliding time window — currently 60 requests per 60 seconds — meant to catch bursts and bugs, not to cap real usage.

Exceeding it returns:

{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded.",
    "request_id": "req_1a2b3c4d5e6f"
  }
}

429 USAGE_LIMIT_EXCEEDED, with a Retry-After header. Wait and retry — this is transient.

Monthly plan quota

A cap on total renders per monthly cycle, based on your plan (see Usage for the exact fields).

The cycle resets on the monthly anniversary of your plan subscription’s start — the same day and time each month. If that day doesn’t exist in a month, it clamps to the last day and returns afterwards (a cycle started on January 31 resets on February 28 or 29, then March 31). Changing plan starts a new subscription, and with it a new cycle. If the subscription start isn’t available, the cycle anchors to your account’s creation date instead.

Exceeding it returns 429 PLAN_QUOTA_EXCEEDED, with no Retry-After — retrying won’t help until the cycle resets. Read monthly_resets_at from GET /v1/usage to know exactly when you can render again, or upgrade your plan.

Checking where you stand

curl https://api.tupsara.com/v1/usage?window_seconds=86400 \
  -H "Authorization: Bearer pdf_live_..."

{
  "total": 42,
  "succeeded": 40,
  "failed": 2,
  "period_start": "2026-08-29T10:15:00Z",
  "period_end": "2026-08-30T10:15:00Z",
  "plan": "free_user",
  "monthly_limit": 100,
  "monthly_used": 37,
  "monthly_remaining": 63,
  "monthly_period_start": "2026-08-03T08:30:00Z",
  "monthly_resets_at": "2026-09-03T08:30:00Z"
}

monthly_used / monthly_remaining reflect the plan quota, counted from monthly_period_start; monthly_resets_at is when that count next returns to 0. total/succeeded/failed reflect just the window_seconds you asked for and don’t affect the quota.