What the agent does
The agent reads the calls before wrapping them. In an app made from Shopify/shopify-app-template-remix, app/shopify.server.ts builds shopifyApp with ApiVersion.January25, PrismaSessionStorage and AppDistribution.AppStore, and exports authenticate. app/routes/app._index.tsx is where the Admin API is called: the action runs admin.graphql twice back to back, a productCreate mutation and then productVariantsBulkUpdate, reads each with await response.json(), and walks responseJson.data!.productCreate!.product! with non-null assertions and no error handling at all. package.json has @shopify/shopify-app-remix at ^4.1.0 and @remix-run/* at 2.16, no test script and no test runner, though .eslintrc.cjs already extends @remix-run/eslint-config/jest-testing-library. shopify.app.toml asks for write_products, and .github/workflows/ci.yml only installs on three Node versions.
Then it reads how the library already retries, in node_modules. admin.graphql(query, { variables, tries }) hands retries: tries - 1 to @shopify/shopify-api's GraphQL client, whose HTTP layer retries only a 429 or 503, sleeping for Retry-After or one second, up to three retries. A cost-throttled query is not that case: the Admin API answers 200 with a GraphQL error whose extensions.code is THROTTLED, the client turns any 200 with GraphQL errors into a GraphqlQueryError carrying the body, and nothing retries it. The body is useful, though: every answer carries extensions.cost.throttleStatus with maximumAvailable, currentlyAvailable and restoreRate, and the error names requestedQueryCost. So tries covers the daily resource throttle that does answer 429, and the agent writes the part that is missing.
It adds app/admin.server.ts with graphqlWithRetry(admin, query, { variables, tries }). The function calls admin.graphql with tries so 429 and 503 keep the library's handling, catches GraphqlQueryError from @shopify/shopify-api, and checks body.errors.graphQLErrors for an entry whose extensions.code is THROTTLED. For that case it reads extensions.cost, waits (requestedQueryCost - currentlyAvailable) / restoreRate seconds with a floor of one second and a little jitter, logs one line with those three numbers, and calls again, up to the attempt count. Any other GraphQL error is rethrown with its messages joined, and the parsed JSON is returned so the index action's existing property chains keep working. The two calls in app._index.tsx move to the wrapper; a mutation's userErrors are left to the caller, since they are not transport failures.
Tests come with it. The agent adds vitest and app/admin.server.test.ts with a fake admin whose graphql throws a GraphqlQueryError built with a THROTTLED body once and then returns a JSON Response; with vi.useFakeTimers() the test asserts the single wait computed from the cost figures, that a MAX_COST_EXCEEDED error is not retried, and that attempts stop at the limit. npm run lint, npx tsc --noEmit and npm run build (remix vite:build) run last. No shop is involved: shopify app dev needs a Partner account and a tunnel, so the run proves the wrapper against the fake and says so.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "The Admin API calls in app/routes/app._index.tsx have no handling for throttling. Read how admin.graphql retries in node_modules first: tries only covers 429 and 503, while a cost-throttled query comes back as a 200 with a THROTTLED GraphQL error that throws GraphqlQueryError. Add app/admin.server.ts with a graphqlWithRetry function that passes tries through, catches GraphqlQueryError, and for a THROTTLED error reads extensions.cost, waits (requestedQueryCost - currentlyAvailable) / restoreRate seconds with a one second floor and jitter, logs the numbers and retries up to the attempt count; rethrow any other GraphQL error with its messages. Move both calls in the index action to it. Add vitest and tests with a fake admin.graphql that throws a THROTTLED error once, using fake timers to assert the wait, plus a non-retried error and the attempt limit. Run lint, tsc and the build. Open a pull request quoting the test output and say no store was used.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds app/admin.server.ts and app/admin.server.test.ts, moves the two calls in app/routes/app._index.tsx to the wrapper, and adds vitest with a test script to package.json. Its description quotes the vitest run output, the lint, type check and build results, and explains in a few lines which failures the library retries and which the wrapper handles, with the file in node_modules it read that from.
A reviewer checks that the wait is computed from the response's own cost figures rather than a fixed sleep, that attempts are bounded so a throttled store cannot hold a request open forever, and that a userErrors array still reaches the caller unchanged. The transcript at GET /o/{org}/sessions/{id}/messages has the library source it read and the test run in full.
The wrapper does not change what the app asks Shopify for, so no scope or shopify.app.toml change ships with it, and shopify app deploy is not part of the run.
Run it on every new route that calls the Admin API
Each new loader or action that calls admin.graphql is the same job once the wrapper exists: use it, and add a test for the failure path. Add an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and a prompt that finds direct admin.graphql calls in the pull request's diff, moves them to the wrapper and comments with what it changed. The trigger adds the pull request after the prompt; it fills in no placeholder.
From your own server, the same run starts with this body and the pull request URL in resources, with a request_id that is a UUID v5 of the head commit so a retried send returns the run already begun.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The retry a library already does and the one it does not are two different failures, and telling them apart means reading the client's source rather than its README. The agent reads it in node_modules, writes the wrapper against what it found, and proves the wait with fake timers, all in the transcript. On a laptop that is an afternoon of reading between other work, and the finding is usually not written down.
Several apps on the same template each get a run, a wrapper and a pull request of their own, in parallel. Because each run reads the installed version of the client, an app pinned to a different @shopify/shopify-app-remix gets a wrapper written for that version rather than a copied file.
Frequently asked questions
Isn't tries enough?
tries retries a 429 and a 503 with Retry-After, which covers the daily resource-based throttle on product mutations. A cost-throttled query answers 200 with a THROTTLED GraphQL error and is thrown, not retried. The wrapper keeps tries for the first case and adds the second.
How long does it wait?
As long as the bucket needs: (requestedQueryCost - currentlyAvailable) / restoreRate seconds from the error's own extensions.cost, with a one second floor and jitter so parallel requests do not retry in step. The numbers come from the response, not from a guess about the store's plan.
Can it test against a real development store?
Not in this run. A real call needs shopify app dev, a Partner account, a store and a tunnel, none of which the sandbox has. The tests drive the wrapper with a fake admin.graphql; a follow-up with a store's credentials as Project secrets could add a smoke test, and the pull request says the wrapper was not run against a store.
What about REST calls?
The template makes none; admin.rest is not used in any route. If your app does, say so in the prompt and the agent wraps those with the same bounded retry on HttpThrottlingError, which carries retryAfter from the REST API's header.