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 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.

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 0 or missing, QRForge treats it as no minute-level limit.
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 0 or missing, QRForge treats it as no daily limit.
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.

HTTP Status Codes

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

HTTP Status	Description
`429`	Rate limit exceeded (minute or day)

Use the code field to distinguish which limit was hit:

rate_limit_minute
rate_limit_day

Best Practices

To build resilient integrations with QRForge:

Centralize API calls
- Route all outbound requests through a shared client or service layer where you can implement retries and tracking.
Implement backoff & jitter
- On rate_limit_minute, retry after a delay and add random jitter to avoid synchronized retries.
Use idempotent designs
- For create/update flows, design your client logic so that safe retries do not accidentally duplicate resources.
Monitor usage
- Surface your own internal counters/metrics for how many requests your system is making toward QRForge.
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

Overview​

Per-Minute Limit​

Error when minute limit is exceeded​

Per-Day Limit​

Error when daily limit is exceeded​

HTTP Status Codes​

Best Practices​

Support​