FlowRelay
Agent Access
Agent and API rate limits
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 | Response | Meaning |
|---|---|---|
| Plan capacity is exhausted | 402 | Upgrade, wait for renewal, or ask FlowRelay about approved custom capacity. |
| Automated work is too broad, too fast, or repeating side effects | 429 | Wait, narrow the next request, reuse existing previews or context, and avoid retry loops. |
| Valid signed events arrive while event capacity remains | Accepted durably | 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 | What it covers | Limit |
|---|---|---|
| Agent Operations reads | Compact setup and plan checks plus richer event, endpoint, diagnostics, reliability, and history reads. | 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. |
| Action previews | Replay previews, diagnostics previews, endpoint tests, endpoint edits, endpoint deletes, and secret-rotation previews. | 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. |
| Confirmed actions | Approved diagnostics sharing and confirmed setup or credential changes after preview, confirmation, idempotency, and audit. | 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. |
| Rejected or malformed ingest | Unknown endpoints, deleted endpoints, bad authentication, repeated invalid requests, invalid JSON, or invalid payload shape. | 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 agentsUse this when pasting the policy into an agent context window.
- OpenAPI contractUse 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 | Meaning |
|---|---|
| Retry-After | HTTP header with the number of seconds the client should wait before trying again. |
| retryAfterSeconds | JSON copy of the retry delay for agents or clients that prefer response-body guidance. |
| resetAt | ISO timestamp for when the current rate-limit window resets. |
| rateLimitClass | The class that was throttled, such as agent_simple_read, action_preview, or failed_endpoint_auth. |
| scope | The scope of the limit, such as agent_grant, installation, endpoint, or ip. |
| recommendedAction | 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 | Behavior |
|---|---|
| A 429 response appears | Wait for Retry-After or retryAfterSeconds before trying again. |
| The request was a broad read | Narrow the endpoint, event, or time range, or switch to a compact read first. |
| The request was an action preview | Reuse the latest applicable preview instead of rebuilding the same proposal repeatedly. |
| The request was an executed action | Reuse the approved idempotency key only when retrying the same approved action. |
| The request was invalid ingest | 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 | Fair-use posture |
|---|---|
| Agent Operations reads | Included with governed access. Use compact reads first, avoid broad polling, and read plan-usage before high-volume loops. |
| Action previews | Preview-first work is encouraged, but repeated proposal loops may be reviewed or slowed. |
| Executed actions | Confirmed recovery, setup, and credential actions remain auditable and can be paused if a workflow appears abusive or unsafe. |
| Diagnostics and replay | 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.