Usage limits

# Usage limits

Canonical: https://docs.flowrelay.app/operate/usage-limits/
Markdown: https://docs.flowrelay.app/operate/usage-limits.md

Use this page to choose a plan, prepare setup or migration volume, and understand what happens when FlowRelay reaches a usage boundary.

## Quick answer
FlowRelay responds differently depending on what ran out. If your plan's event capacity is used up, new events get a 402 Payment Required response — nothing is billed silently; you choose whether to upgrade, wait for the next period, or request approved custom capacity. If an automated client is looping too fast, or the traffic is invalid, the response is 429 Too Many Requests with guidance on when to retry. Normal signed events from your senders are stored durably on arrival while capacity remains, and FlowRelay paces the Shopify Flow handoff from there.


- Situation: Event capacity is exhausted; Response: 402; What to do: Upgrade, wait for the next period, or ask FlowRelay about approved custom capacity.
- Situation: Paid-plan event grace is exhausted; Response: 402; What to do: Approve more capacity before sending more production traffic.
- Situation: An agent, sender, or client is looping too quickly; Response: 429; What to do: Obey Retry-After, narrow the request, and avoid tight retry loops.
- Situation: A sender sends valid signed events while capacity remains; Response: Accepted durably; What to do: Let FlowRelay buffer intake and pace downstream Shopify Flow handoff.
- Situation: Agent or recovery usage is unusually heavy; Response: Fair-use review; What to do: Use compact reads first, check plan-usage, and ask support before migration or backfill windows.

## Plan capacity
These are the public plan limits most merchants compare first: event intake, recovery tools, Agent Access posture, and retained event history.


- Plan: Free/Test; Accepted events: 500; Diagnostics shares: 25; Replay executions: 25; Agent Access: Included safeguards; Event history: 30 days
- Plan: Starter; Accepted events: 25,000; Diagnostics shares: 1,000; Replay executions: 500; Agent Access: Included safeguards; Event history: 30 days
- Plan: Growth; Accepted events: 250,000; Diagnostics shares: 10,000; Replay executions: 5,000; Agent Access: Included safeguards; Event history: 30 days
- Plan: Scale; Accepted events: 1,000,000; Diagnostics shares: 50,000; Replay executions: 25,000; Agent Access: Expanded safeguards; Event history: 30 days

## Paid-plan event grace
Starter, Growth, and Scale include bounded event-intake grace after the included accepted-event cap is reached. Events accepted during grace are still stored, metered, and handed off normally when the receipt path succeeds. FlowRelay does not create silent overage charges; more capacity requires an explicit upgrade, approved add-on, or custom-capacity approval.


## What counts against usage
The embedded Plan page and Agent Operations plan-usage response show current usage and enforcement state. Use them for capacity planning, monitoring cadence, and setup or recovery work.


- Usage: Accepted events; What counts: Inbound events accepted by FlowRelay for processing during the plan period; How it is limited: Plan capacity. Paid plans include bounded event-intake grace after the included cap.
- Usage: Diagnostics shares; What counts: Private, redacted diagnostics shares created for support, a partner, or an authorized agent; How it is limited: Included recovery-tool allowance plus fair-use review.
- Usage: Replay executions; What counts: Intentional reruns of retained events. Replay can repeat downstream actions; How it is limited: Included recovery-tool allowance plus fair-use review.
- Usage: Agent Operations reads; What counts: Compact setup and plan checks plus richer event, endpoint, diagnostics, reliability, or history reads; How it is limited: Short-window rate limits, scoped grants, and sustained fair-use review.
- Usage: Action previews; What counts: Preview or proposal records for approved actions before anything changes; How it is limited: Short-window rate limits, confirmation, idempotency, audit, and sustained fair-use review.
- Usage: Executed actions; What counts: Confirmed approved actions such as diagnostics-share creation, endpoint tests, endpoint changes, or secret rotation; How it is limited: Short-window rate limits, confirmation, idempotency, audit, and sustained fair-use review.

## Operational safeguards
Usage limits are not just plan counters. FlowRelay also protects operators from unsafe loops, repeated recovery actions, and bad traffic. Exact 429 response details live in the Agent and API rate limits guide.

- [Agent and API rate limits](https://docs.flowrelay.app/agent-access/rate-limits-and-backoff/): See exact 429 response fields, retry behavior, and machine-readable rate-limit classes.

- Situation: Valid signed event intake; How FlowRelay handles it: Eligible events are accepted durably while plan capacity remains, then FlowRelay paces downstream Shopify Flow handoff.
- Situation: Agent and API work; How FlowRelay handles it: Automated reads, previews, and approved actions use short-window rate limits so agents can avoid tight loops and unsafe repetition.
- Situation: Recovery work; How FlowRelay handles it: Replay, diagnostics, endpoint changes, and secret rotation stay preview-first, explicit, auditable, and paced.
- Situation: Invalid or malformed traffic; How FlowRelay handles it: Bad endpoint URLs, failed authentication, and malformed payloads can receive 429 responses before they burn event capacity.

## Recovery visibility at limits
Existing event history, receipts, error context, diagnostics, replay history, and recovery guidance stay visible when a limit is reached or event intake is in grace. The operator can still decide whether to upgrade, request custom capacity, wait for the next period, or reduce limit-consuming work.


## What usage limits do not change
Usage limits do not create configurable retry schedules, custom endpoint-level throttling, user-managed queue buffering, a default sender-facing throttle for valid signed event bursts, or general webhook traffic management.


## Operating guidance
Apply the concept through the receipt before changing setup, resending, or replaying.
- Treat a 402 Payment Required response as a capacity stop: upgrade, wait for the next period, or ask about approved custom capacity.
- Use plan-usage before broad agent reads, repeated action previews, migration work, or high-volume recovery.
- Valid signed events are stored durably on arrival while event capacity remains; FlowRelay then paces the Shopify Flow handoff.
- Use the Agent and API rate limits guide when an agent, CLI, MCP client, API client, or sender receives 429.

## Related
- [Rate limits](https://docs.flowrelay.app/agent-access/rate-limits-and-backoff.md)
- [Support codes](https://docs.flowrelay.app/recover/error-codes.md)
- [Grants and scopes](https://docs.flowrelay.app/agent-access/grants-and-scopes.md)

## Safety Boundary
Do not share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.