# Agent and API rate limits Canonical: https://docs.flowrelay.app/agent-access/rate-limits-and-backoff/ Markdown: https://docs.flowrelay.app/agent-access/rate-limits-and-backoff.md FlowRelay separates plan capacity from operational safeguards. Normal signed events are accepted durably while capacity remains; automated/API loops may receive 429 with retry guidance. ## Policy at a glance FlowRelay separates plan capacity from automation safeguards. Capacity, automated work, and valid signed event intake have different responses because they represent different risks. - Situation: Plan capacity is exhausted; Response: 402; Meaning: Upgrade, wait for renewal, or ask FlowRelay about approved custom capacity. - Situation: Automated work is too broad, too fast, or repeating side effects; Response: 429; Meaning: Wait, narrow the next request, reuse existing previews or context, and avoid retry loops. - Situation: Valid signed events arrive while event capacity remains; Response: Accepted durably; Meaning: FlowRelay stores the event facts and processes the Shopify Flow handoff asynchronously. ## Rate-limit groups These are grouped by public behavior, not every internal route name. They are here for planning, but the live 429 response remains the source of truth for the exact class and scope. - Family: Agent Operations reads; What it covers: Compact setup and plan checks plus richer event, endpoint, diagnostics, reliability, and history reads.; Limit: Simple reads: 120 per minute per agent grant. 600 per minute per store installation. Rich reads: 30 per minute per agent grant. 150 per minute per store installation. - Family: Action previews; What it covers: Replay previews, diagnostics previews, endpoint tests, endpoint edits, endpoint deletes, and secret-rotation previews.; Limit: Recovery and diagnostics previews: 20 per minute per agent grant. 100 per minute per store installation. Endpoint or credential previews: 10 per minute per agent grant. 50 per minute per store installation. All previews combined: 30 per minute per agent grant. 150 per minute per store installation. - Family: Confirmed actions; What it covers: Approved diagnostics sharing and confirmed setup or credential changes after preview, confirmation, idempotency, and audit.; Limit: Diagnostics shares: 10 per minute per agent grant. 50 per minute per store installation. Endpoint or secret-changing executions: 5 per minute per agent grant. 25 per minute per store installation. Non-replay executions combined: 10 per minute per agent grant. 50 per minute per store installation. - Family: Rejected or malformed ingest; What it covers: Unknown endpoints, deleted endpoints, bad authentication, repeated invalid requests, invalid JSON, or invalid payload shape.; Limit: Invalid requests: 30 per minute per IP. 300 per hour per IP. Failed endpoint authentication: 100 per hour per endpoint. Malformed payloads: 100 per hour per endpoint. ## Why limits differ FlowRelay does not use one global rate limit. Routine reads, replay previews, credential changes, and rejected sender traffic carry different levels of risk, so each category has its own safeguard. Operators do not need to memorize the full set. Share the Markdown page or OpenAPI contract with the authorized agent or API client, then let the client follow the 429 response fields. Each 429 response identifies the limited class, affected scope, retry timing, and recommended behavior. - [Markdown version for agents](https://docs.flowrelay.app/agent-access/rate-limits-and-backoff.md): Use this when pasting the policy into an agent context window. - [OpenAPI contract](https://docs.flowrelay.app/reference/openapi/agent-operations.openapi.json): Use this for machine-readable response schemas and exact operation behavior. ## 429 response fields Every 429 response tells the client how to wait and what to change. Agents should follow these fields instead of relying on prose or hard-coded guesses. - Field: Retry-After; Meaning: HTTP header with the number of seconds the client should wait before trying again. - Field: retryAfterSeconds; Meaning: JSON copy of the retry delay for agents or clients that prefer response-body guidance. - Field: resetAt; Meaning: ISO timestamp for when the current rate-limit window resets. - Field: rateLimitClass; Meaning: The class that was throttled, such as agent_simple_read, action_preview, or failed_endpoint_auth. - Field: scope; Meaning: The scope of the limit, such as agent_grant, installation, endpoint, or ip. - Field: recommendedAction; Meaning: Plain-language guidance to wait, narrow the request, use compact reads, or stop a loop. ## Response checklist Use the response fields first, then choose the smallest safe next request. The goal is to slow the loop, reduce scope, or reuse existing approval context. - Condition: A 429 response appears; Behavior: Wait for Retry-After or retryAfterSeconds before trying again. - Condition: The request was a broad read; Behavior: Narrow the endpoint, event, or time range, or switch to a compact read first. - Condition: The request was an action preview; Behavior: Reuse the latest applicable preview instead of rebuilding the same proposal repeatedly. - Condition: The request was an executed action; Behavior: Reuse the approved idempotency key only when retrying the same approved action. - Condition: The request was invalid ingest; Behavior: Fix the endpoint URL, authentication header, signature, or JSON body before retrying. ## Fair-use posture Agent Access is included with each plan. The rate limits are operational safeguards, not separate charges. Sustained high-volume or unusually risky work can still need review before a migration, backfill, or recovery window. - Surface: Agent Operations reads; Fair-use posture: Included with governed access. Use compact reads first, avoid broad polling, and read plan-usage before high-volume loops. - Surface: Action previews; Fair-use posture: Preview-first work is encouraged, but repeated proposal loops may be reviewed or slowed. - Surface: Executed actions; Fair-use posture: Confirmed recovery, setup, and credential actions remain auditable and can be paused if a workflow appears abusive or unsafe. - Surface: Diagnostics and replay; Fair-use posture: Recovery tools are included for real support and recovery work, not bulk traffic generation. Ask support before migration, backfill, or unusually large recovery windows. ## Boundaries These rate limits do not create sender-facing burst throttles for normal valid signed events, do not prove downstream Shopify Flow actions completed, and do not let agents approve billing, change grants, access raw secrets, or bypass the selected authority tier. ## Related - [Usage limits](https://docs.flowrelay.app/operate/usage-limits.md) - [Agent orientation](https://docs.flowrelay.app/agent-access/agent-orientation.md) - [Availability and refusals](https://docs.flowrelay.app/agent-access/availability-and-refusals.md) - [API Reference](https://docs.flowrelay.app/reference/api.md) - [MCP Reference](https://docs.flowrelay.app/reference/mcp.md) ## Safety Boundary Do not include raw event bodies, endpoint secrets, authentication headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.