Common Errors
The error types a session records, the tool problems you'll see in its timeline, and the fix for each — scan the FIX lines to triage quickly.
Run errors
These end a run. The session records one of them as its error_type.
The model provider returned an error — typically a rate limit, an overloaded model, or a temporary disruption. Not a store issue. An answer the provider cut off part-way is retried once before the run stops.
FixRetry the session, or switch to a different model.
The model declined the shopping task, or gave no response. Some models have guardrails against "purchasing" or entering payment details on a user's behalf.
FixTry a different model — Choosing Models shows which handle shopping tasks reliably.
The agent hit the configured turn limit (8 by default) without finishing — usually stuck in a loop: re-calling the same tool, misreading a response, or blocked on a required step.
FixReview the session timeline for where it got stuck. Common causes: unclear tool error messages and missing response fields.
The run used more tokens than one run is allowed — usually very large tool responses repeated across turns.
FixTrim what your tools return: default result limits, no full catalogue dumps, and only the fields an agent needs.
Tool problems
A failing tool call doesn't end the run: the store's reply goes back to the agent, which may retry or give up. Look for these in the session timeline.
The agent sent wrong or malformed arguments to a tool — usually the model misreading the tool's input schema: a string where an object is expected, or a required field omitted.
FixReview your tool's JSON Schema and ensure required fields are declared with correct types. Clearer field descriptions help models construct valid calls — see Schema Quality.
The store took too long to answer — common with heavy search queries on large catalogs with no query limits.
FixAdd default result limits, index frequently queried fields, and avoid unbounded queries that scan entire product tables.
The agent used an invalid variant ID adding to cart — usually because the product details response doesn't clearly map option labels ("Blue / Large") to their IDs.
FixInclude variant IDs alongside option labels in your product details response so agents can reliably select the correct variant.
A checkout was created but no URL came back for the user to continue to payment.
FixInclude a continue_url (or checkout URL) in your checkout responses so the user has a destination after the agent finishes.
The JSON-RPC request couldn't reach your endpoint or returned an invalid response.
FixVerify the endpoint is reachable over HTTPS and answers valid JSON-RPC. Deeper diagnosis: Transport Failures.
Store-page (WebMCP) runs
A store-page run can be refused before it starts (sign-in, one task per run, the daily limit, busy browsers) or stop because the page has no WebMCP tools. The messages are listed in Errors & Diagnostics, and page problems in Transport Failures.
Check the session timeline for the exact tool call that produced the error. It shows the full request payload and response, making it easy to pinpoint whether the issue is in the agent's request or the store's response.