Skip to main content

API Rate Limits

QRForge enforces rate limits to protect the stability of the platform and to ensure fair usage across all customers.

Rate limits are per user and are derived from your account-level configuration (plan, add-ons, and internal limits settings). When a limit is exceeded, the API returns a structured error with a dedicated error code.

Overview​

QRForge currently enforces two primary, plan-based rate limits for API requests:

  • Per-minute limit – caps short burst traffic.
  • Per-day limit – caps total daily API usage.

These limits are evaluated on every authenticated request. In addition to these two account-level limits, every API key is also subject to a fixed, independent safety-net ceiling — see Per-Key Backstop Limit below.

Internally, QRForge uses the following concepts on the user object:

  • limits.api_requests_per_minute_max
  • limits.api_requests_per_day_max
  • usage.api_requests_this_minute
  • usage.api_requests_today

You don't need to manage these fields directly — they are maintained by QRForge. They are described here to make platform behavior transparent.

Per-Minute Limit​

The per-minute limit protects the platform from sudden bursts of traffic.

  • If limits.api_requests_per_minute_max is explicitly set to 0, QRForge treats it as no minute-level limit.
  • If the field is missing or not a number, this is not treated as unlimited — QRForge fails closed to a default, enforced cap of 60 requests/minute. This default is applied identically across every API endpoint, so an account that has never had its limits configured is still protected.
  • Otherwise, requests are counted inside a rolling minute window.
  • When usage.api_requests_this_minute exceeds the configured maximum, the API will reject additional requests for the remainder of that window.

Error when minute limit is exceeded​

HTTP status: 429 Too Many Requests
Error code: rate_limit_minute

Example response:

{
  "ok": false,
  "version": "2025-11-14-v1",
  "request_id": "e5e9cfa0-1122-4df4-9f82-8f6e9e8b9e47",
  "code": "rate_limit_minute",
  "message": "Too many requests this minute."
}

Client recommendation:

  • Implement exponential backoff and retry after a short delay (e.g., 10–30 seconds).
  • For batch operations, spread calls over time rather than sending them all at once.

Per-Day Limit​

The per-day limit caps the total number of API calls made by a user within a given 24-hour window.

  • If limits.api_requests_per_day_max is explicitly set to 0, QRForge treats it as no daily limit.
  • If the field is missing or not a number, this is not treated as unlimited — QRForge fails closed to a default, enforced cap of 10,000 requests/day, applied identically across every API endpoint.
  • Otherwise, usage.api_requests_today is incremented for each successful request.
  • When the daily usage exceeds the configured maximum, subsequent requests will fail until the daily window resets.

Error when daily limit is exceeded​

HTTP status: 429 Too Many Requests
Error code: rate_limit_day

Example response:

{
  "ok": false,
  "version": "2025-11-14-v1",
  "request_id": "c94a4dcd-2689-4f48-b0ea-b2d7c7b5e6a2",
  "code": "rate_limit_day",
  "message": "Daily API quota exceeded."
}

Client recommendation:

  • Monitor request volume on your side and stay within your plan quota.
  • For automated clients, prefer queueing and backoff when close to the limit.
  • Consider upgrading your plan if you expect sustained high volumes.

Per-Key Backstop Limit​

In addition to the two plan-based limits above, every API key is also subject to a fixed, account-independent backstop ceiling:

  • 200 requests/minute
  • 100,000 requests/day

This backstop is enforced on every public API endpoint, independently of your plan's per-minute and per-day limits described above. It's set generously above any real plan tier, so it should never trigger during normal use — it exists purely as a safety net against a stale or misconfigured per-account limit.

Error when the backstop is exceeded​

HTTP status: 429 Too Many Requests
Error code: rate_limited

Example response:

{
  "ok": false,
  "version": "2025-11-14-v1",
  "request_id": "9b1e6f2a-4c3d-4a1e-9f0a-2d7c8b6e1a3f",
  "code": "rate_limited",
  "message": "Rate limit exceeded."
}

Responses throttled by this backstop include a Retry-After header (seconds) indicating when to retry.

HTTP Status Codes​

All rate limit errors use HTTP status code 429 Too Many Requests, with a structured JSON body.

HTTP StatusDescription
429Rate limit exceeded (minute, day, or per-key backstop)

Use the code field to distinguish which limit was hit:

  • rate_limit_minute
  • rate_limit_day
  • rate_limited (per-key backstop — see above)

Best Practices​

To build resilient integrations with QRForge:

  1. Centralize API calls

    • Route all outbound requests through a shared client or service layer where you can implement retries and tracking.

  2. Implement backoff & jitter

    • On rate_limit_minute, retry after a delay and add random jitter to avoid synchronized retries.

  3. Use idempotent designs

    • For create/update flows, design your client logic so that safe retries do not accidentally duplicate resources.

  4. Monitor usage

    • Surface your own internal counters/metrics for how many requests your system is making toward QRForge.

  5. Plan capacity with your plan

    • Enterprise plans can have tailored limits. If you anticipate high-volume traffic, contact support to align your limits with your use case.

Support​

If you frequently hit rate limits and need higher quotas, contact us at:

support@qrforge.link