Skip to main content

quota_exceeded

HTTP 402 · code: "quota_exceeded" · type: https://docs.formfeed.dev/errors/quota-exceeded

A live render, batch or PDF tool was refused before anything was rendered, because the organisation has no units left for it in this billing period. period_end is the day the next period starts. Test keys are never refused for this: test renders are not counted.

Example​

{
  "type": "https://docs.formfeed.dev/errors/quota-exceeded",
  "title": "Quota exceeded",
  "status": 402,
  "detail": "The free plan's 100 units for this period are used up",
  "code": "quota_exceeded",
  "period_end": "2026-11-01",
  "request_id": "req_4b7c1e9a2f3d4c5b8a6e7f9012"
}

Common causes​

  • The Free plan has used its 100 units of the period. Free has no overage, so live renders stop until the next period.
  • A paid plan reached its hard cap: the included units, the prepaid units of bought packs, and overage worth three times the plan's monthly price. Then detail reads Overage for this period reached the hard cap of … units, the problem carries hard_cap_units, and automatic top-up is off.
  • A batch needs at least one unit per item, and fewer are left (The batch needs at least 40 units; 12 remain in this period). Nothing of the batch is queued.

A paid plan's period runs monthly from the day of the subscription, not by calendar month; see Billing periods and When units run out.

How to fix it​

  • Wait for the next period (period_end), upgrade the plan, or buy a unit pack on the billing page.
  • On a paid plan, buy a prepaid unit pack on the Billing page: its units raise the hard cap at once.
  • Keep developing with a test key: test renders are not metered.
  • Subscribe to the quota.warning webhook to hear about it when 80 % of the included units are used.

Retry?​

Not until units are available again. Then send the request again with a new Idempotency-Key or without one: a 4xx answer is stored under its key for 24 hours, so the old key returns this problem again. See retrying.