Common Errors

Common errors

The error types a run records, the tool problems you'll see in its trace, and the fix for each. Scan the fix lines to triage quickly.

Run errors

These end a run, which then ends as Failed. The run records one of them as its error_type.

openrouter_error

The model provider returned an error: usually 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.

FixStart the run again, or switch to a different model with the Model pill.

model_refused

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.

max_turns_exceeded

The agent hit the 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.

FixRead the run's Trace and Timeline tabs to find where it got stuck. Common causes: unclear tool error messages and missing response fields.

token_limit_exceeded

The run used more tokens than one run is allowed, usually because of 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 run's Trace tab, which also says whose fault each error was: the store, the agent, or ours.

Invalid tool arguments

The agent sent wrong or malformed arguments to a tool, usually because the model misread 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 build valid calls. See Schema quality.

Tool call timed out

The store took too long to answer. This is 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.

Wrong variant ID

The agent used an invalid variant ID when adding to the 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.

No checkout URL

A checkout was created but no URL came back for the buyer to continue to payment.

FixInclude a continue_url (or checkout URL) in your checkout responses so the buyer has somewhere to go after the agent finishes.

MCP transport failure

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. More detail: Transport failures.

Website (WebMCP) runs

A website 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 and diagnostics, and page problems in Transport failures.

Tip

Find the exact tool call that produced the error in the run's Trace tab. It shows the full request and response, so you can see whether the problem is in the agent's request or the store's response.

Something wrong on this page?