Errors and diagnostics
Every error shape the harness returns, and how to tell a failed request from a failed run.
API errors
| Status | Shape | When |
|---|---|---|
401 | { "message": … } | Missing, invalid, or expired token. |
403 | { "message": … } | The token lacks the route's ability, or the team role doesn't permit the write. |
404 | { "message": … } | Unknown ID, or an ID outside your workspace. The two look the same on purpose. |
409 | { "message": …, "id": "<ulid>" } | Saving a target whose domain already exists in the workspace. The existing target's ID is returned so you can adopt it instead of retrying. |
422 | { "message": …, "errors": { field: [msgs] } } | Validation. errors maps each field to its messages. |
429 | { "message": … } | Rate limited. See limits. |
A failed run is not an HTTP error
A run that can't complete (the store unreachable, a transport failure part-way, a model error) still returns 200. The failure is carried in the result: error (the message) and error_type (a stable classifier), alongside whatever the run did complete. This is deliberate: the run happened, and its partial record is the diagnostic.
Messages when you start a run
Some runs are refused before they start. Runs shows the message as written here. Some of these messages still use older words ("session", "store-page"): a store-page run is a website run.
| Status | Message | What to do |
|---|---|---|
429 | Daily session limit reached (used/limit). Sign in for a higher limit. Resets … | Signed out, runs are capped per day. Sign in, or wait for the reset. |
429 | Monthly session limit reached (used/limit). Resets … | Your plan's monthly cap. See Usage. |
401 | Sign in to run the store-page door. | Website runs need an account. Sign in and run again. |
422 | A store-page run is one task on our browser. Start a new session to run another. | A website run takes no follow-up messages. Start a new run on Runs. |
429 | You have used today's 10 store-page runs. They reset at midnight UTC. | Set How the agent reaches the store to UCP, or wait for the reset. |
429 | All store-page browsers are still busy. Try again in a minute. | The run waited for a free browser and none came. Try again shortly. |
Inspect refuses to start only when a store's profile lists neither an MCP nor a REST service: "This store publishes no UCP MCP or REST endpoint to inspect." A store with REST and no MCP is inspected over REST; choosing MCP for a call there answers "This store publishes no UCP MCP endpoint. Its calls go over REST."
A website run can also fail at the start because of the page itself: "The page has no WebMCP (document.modelContext).", "The page registered no WebMCP tools.", or "The browser could not open the page: …". See Transport failures.
Transport diagnostics
Each tool call in a run's record carries the full exchange: method, URL, request body, response status and body. When the call failed before any response (connection refused, timeout), the same record appears with a null status and an error field instead, so the run's Trace tab always shows what was attempted, not just what answered. Bodies are truncated at 4,000 characters, marked with a … (truncated) suffix.
For the failures themselves (MCP handshake errors, REST fallback, OAuth), see Transport failures and Common errors.
Reference-store rejections
The reference store answers differently at its enforcement edge, with an error code plus a stable reason:
{ "error": "tap_verification_failed", "reason": "signature expired" }The full reason table lives in Signature Verification.
Webhook verification failures
If your endpoint rejects a collection-run webhook delivery, check the signature over the raw body: X-Playground-Signature is sha256= + HMAC-SHA256(raw bytes, webhook secret). The most common mismatch is verifying over re-serialised JSON: key order and escaping change the bytes. Compare digests constant-time, and remember deliveries never follow redirects.
Error messages may be reworded; treat shapes, status codes, error_type, and the reference store's reason strings as the stable contract.
Something wrong on this page?