API reference
Errors
One error shape for every endpoint, and every code with what to do about it.
Every failed request returns the same JSON body. Branch on code: it is stable. message is for people and may change.
The error object
Fields
- errorobject
The only key of an error body.
- codestring
One of the codes on this page.
- messagestring
A short description for people.
- request_idstring
The ID of the request, the same value as the
X-Request-Idresponse header. Quote it when you report a problem. - detailsobject
Only on some errors.
invalid_requestsetsfieldorindexto say where the problem is;concurrency_limit,mcp_connection_limitandconnection_limitsetlimit.
The 429 codes and capacity_unavailable also set a Retry-After response header, in seconds.
not_found and method_not_allowed are answered with or without an API key.
{
"error": {
"code": "concurrency_limit",
"message": "concurrent session limit reached",
"request_id": "req_5d1c0e7a9b3f",
"details": { "limit": 5 }
}
}Where errors appear
- HTTP calls return the error object with the HTTP status listed under Error codes.
- A step of Actions that fails does not fail the call. The response is
200withok: false, and the failed step carriescodeandmessage. That includes a selector or XPath the page cannot parse: inside/actionsit is a step error, not a400. cdp_urland the live view answer with the error object when the connection is refused:invalid_tokenorconnection_limiton the WebSocket handshake.- MCP tools return a tool error whose text is
<code>: <message>. - Agent runs that fail have status
failed, withcodeandmessageinerroron the run and in theerrorevent.
{
"ok": false,
"completed": 0,
"results": [
{
"type": "click", "ok": false, "duration_ms": 31,
"error": {
"code": "element_not_found",
"message": "no element matched"
}
}
],
"url": "https://example.com/login",
"title": "Log in"
}element_not_found: no element matchedError codes
| HTTP | Code | When | What to do |
|---|---|---|---|
| 400 | invalid_request | Malformed JSON, unknown field, bad value, bad selector or XPath. Inside /actions a bad selector or XPath is a step error in a 200 | Fix the request. details.field or details.index says where |
| 401 | unauthorized | Missing or invalid API key | Send Authorization: Bearer with a valid key |
| 403 | invalid_token | Bad or expired token on cdp_url or live_view_url | Get new URLs from POST /v1/sessions/{id}/tokens |
| 404 | not_found | No such route under /v1 or /mcp | Check the path |
| 404 | session_not_found | No such session for this key | Check the ID and that this key created the session |
| 404 | element_not_found | No element matched the locator | Check the locator. List what is on the page with /elements |
| 404 | tab_not_found | No such tab | List the open tabs with GET /v1/sessions/{id}/tabs |
| 404 | run_not_found | No such run for this key | Check the ID and that this key started the run |
| 405 | method_not_allowed | The route exists under another method | Use a method from the Allow response header |
| 409 | session_in_use | Another drive call has been running on this session for more than 3 s | Retry |
| 409 | no_page_loaded | The tab is blank | Navigate first |
| 409 | last_tab | Tried to close the only tab | Open another tab first, or delete the session |
| 409 | run_in_progress | The session already has an active run | Wait for that run to end, or cancel it |
| 410 | session_closed | The session has ended | Create a new session. Pass the old sphynx_id to come back as the same device |
| 422 | unknown_region | region is not a known region | Use a code from GET /v1/regions |
| 422 | sphynx_id_not_found | No such sphynx_id | Use the sphynx_id of an earlier session, or leave it out |
| 422 | unsupported_country | Not in GET /v1/proxy/countries | Use a country from that list |
| 422 | proxy_invalid | Bad proxy object | Fix proxy. message says what is wrong |
| 422 | unsafe_url | Not http/https, or a private, loopback or link-local address | Use a public http or https URL |
| 422 | model_not_allowed | model is not on the server's list for agent runs | Leave model out to use the server default |
| 429 | concurrency_limit | Too many live sessions for this key. Retry-After is set | Delete a session, or wait Retry-After seconds and retry |
| 429 | mcp_connection_limit | Too many open MCP connections for this key: at most twice its concurrency limit. details.limit says how many. Retry-After is set | Close MCP clients you no longer use, or wait Retry-After seconds |
| 429 | connection_limit | Too many open connections to one session: 10 on cdp_url, 5 on the live view. details.limit is the cap. Retry-After is set | Disconnect a client or close a viewer, then connect again |
| 500 | internal | Our fault | Send us the request_id |
| 502 | proxy_unreachable | Could not connect through the proxy | Check the proxy address and credentials, then retry |
| 502 | session_launch_failed | The browser failed to start | Retry |
| 502 | navigation_failed | DNS failure, connection refused, TLS error | Check the URL, then retry |
| 503 | capacity_unavailable | The host is full. Retry-After is set | Wait Retry-After seconds and retry |
| 503 | residential_unavailable | Residential proxy is not configured or not reachable | Retry later, or use another proxy type |
| 503 | agent_unavailable | The server has no model credentials configured | Agent runs are not available on this deployment |
| 504 | navigation_timeout | The page did not reach wait_until in timeout_ms, or a start_url did not load in 30 s | Raise timeout_ms, or wait for domcontentloaded |
| 504 | wait_timeout | A wait step timed out. Only inside an /actions result | Raise the step's timeout_ms, or check the locator |
Run failure codes
A run that starts and then fails reports one of these in error.code on the run and in the error event. cancelled is a status, not an error.
| Code | When | What to do |
|---|---|---|
max_steps_exceeded | The agent needed more than max_steps tool calls | Raise max_steps, up to 100, or narrow the task |
session_closed | The session ended during the run | Start a new run. Raise the session's timeouts if they cut it short |
model_error | The model call failed | Start the run again |
result_invalid | The result did not match result_schema, or the run ended without one | Simplify the schema, or say in the task what each field should hold |
internal | Our fault | Start the run again. Send us the run ID if it repeats |