Rate limits and metering

Per-minute rate limit

The effective limit is:

max(platform ceiling, plan.api_rate_limit_per_min)

• Platform ceiling: 60 requests/minute (API_RATE_LIMIT_PER_MIN)
• Plan limit: stored on plans.api_rate_limit_per_min (0 = platform only)

Your current limit is returned by GET /v1/status in api.rate_limit_per_min.

Per-plan limits (seeded defaults)

When a plan's api_rate_limit_per_min is 0, only the platform ceiling applies. Otherwise the higher of the platform ceiling and plan value wins.

HTTP 429 — too many requests

When the per-minute limit is exceeded, the API responds with status 429 and:

• Retry-After header — seconds until the window resets
• Link header — points to this documentation page
• JSON body with message, retry_after, and documentation

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Link: <https://docs.qrhero.com/api/rate-limits>; rel="help"; type="text/html"
Content-Type: application/json

{
  "message": "Too many API requests.",
  "retry_after": 42,
  "documentation": "https://docs.qrhero.com/api/rate-limits"
}

Clients should honour Retry-After before retrying.

Heavy endpoints — raw export bucket

GET /v1/analytics/qr-codes/{code_ulid}/raw-export has an additional, stricter per-minute limit on top of the standard org bucket:

• Raw export rate: 6 requests/minute (API_RAW_EXPORT_RATE_LIMIT_PER_MIN)
• Default page size: 1,000 rows (API_RAW_EXPORT_DEFAULT_LIMIT)
• Maximum page size: 5,000 rows (API_RAW_EXPORT_MAX_LIMIT)

Use the rollup endpoint for dashboard-style metrics; reserve raw export for bulk data pulls.

Monthly included calls and overage

Billable operations increment api_usage. Each plan defines api_calls_included_month included calls. Usage beyond the included quota draws from the organization's prepaid wallet at 1 minor units per call (API_COST_PER_CALL_MINOR).

Check api.calls_included_month and api.calls_used_month on GET /v1/status. Token CRUD endpoints under /v1/tokens are not metered as billable API usage.

MCP

MCP tool invocations share the same per-minute rate limit and monthly metering as the equivalent REST endpoint. A rate-limited MCP call returns the same 429 payload and headers.