After every successful GraphQL response, read `extensions.cost.requestedQueryCost`, `extensions.cost.actualQueryCost`, and `extensions.cost.throttleStatus` — these fields are present on all Admin GraphQL responses regardless of HTTP status code
From `throttleStatus`, read `maximumAvailable` (total bucket capacity), `currentlyAvailable` (remaining points), and `restoreRate` (points restored per second) to understand your current rate limit state
Before dispatching each request, check `currentlyAvailable` against the estimated cost of the next query; if `currentlyAvailable` is below a safe threshold (e.g., 200 points), calculate the wait time as `(threshold - currentlyAvailable) / restoreRate` seconds and delay the next request
When a request is throttled, Shopify returns HTTP 200 with a `THROTTLED` error code in `errors[0].extensions.code` — check for this code (not HTTP 429) and back off exponentially before retrying
Use the `actualQueryCost` from the response (which may be less than `requestedQueryCost` for queries that return fewer results than the estimated maximum) to refund the difference to your local token bucket model
For high-throughput apps, implement a request queue with a leaky-bucket algorithm client-side, using `restoreRate` and `currentlyAvailable` from the last response to gate request dispatch
Known gotchas
Shopify returns HTTP 200 (not 429) for throttled GraphQL requests — if your error handling only checks HTTP status codes, throttling errors will be silently swallowed and retries will never fire
requestedQueryCost is calculated statically before execution and may exceed actualQueryCost when paginated connections return fewer nodes than the maximum; the difference is credited back but your client must read actualQueryCost to track this accurately
The extensions.cost object is only present on Admin GraphQL API responses — the Storefront API uses a different rate limiting mechanism (request count per second) and does not include extensions.cost
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp