SPHYNX
esc
  • Loading
Open console

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-Id response header. Quote it when you report a problem.

    • detailsobject

      Only on some errors. invalid_request sets field or index to say where the problem is; concurrency_limit, mcp_connection_limit and connection_limit set limit.

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.

429
{
  "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 200 with ok: false, and the failed step carries code and message. That includes a selector or XPath the page cannot parse: inside /actions it is a step error, not a 400.
  • cdp_url and the live view answer with the error object when the connection is refused: invalid_token or connection_limit on the WebSocket handshake.
  • MCP tools return a tool error whose text is <code>: <message>.
  • Agent runs that fail have status failed, with code and message in error on the run and in the error event.
200 · a failed step of /actions
{
  "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"
}
A failed MCP tool call
element_not_found: no element matched

Error codes

HTTPCodeWhenWhat to do
400invalid_requestMalformed JSON, unknown field, bad value, bad selector or XPath. Inside /actions a bad selector or XPath is a step error in a 200Fix the request. details.field or details.index says where
401unauthorizedMissing or invalid API keySend Authorization: Bearer with a valid key
403invalid_tokenBad or expired token on cdp_url or live_view_urlGet new URLs from POST /v1/sessions/{id}/tokens
404not_foundNo such route under /v1 or /mcpCheck the path
404session_not_foundNo such session for this keyCheck the ID and that this key created the session
404element_not_foundNo element matched the locatorCheck the locator. List what is on the page with /elements
404tab_not_foundNo such tabList the open tabs with GET /v1/sessions/{id}/tabs
404run_not_foundNo such run for this keyCheck the ID and that this key started the run
405method_not_allowedThe route exists under another methodUse a method from the Allow response header
409session_in_useAnother drive call has been running on this session for more than 3 sRetry
409no_page_loadedThe tab is blankNavigate first
409last_tabTried to close the only tabOpen another tab first, or delete the session
409run_in_progressThe session already has an active runWait for that run to end, or cancel it
410session_closedThe session has endedCreate a new session. Pass the old sphynx_id to come back as the same device
422unknown_regionregion is not a known regionUse a code from GET /v1/regions
422sphynx_id_not_foundNo such sphynx_idUse the sphynx_id of an earlier session, or leave it out
422unsupported_countryNot in GET /v1/proxy/countriesUse a country from that list
422proxy_invalidBad proxy objectFix proxy. message says what is wrong
422unsafe_urlNot http/https, or a private, loopback or link-local addressUse a public http or https URL
422model_not_allowedmodel is not on the server's list for agent runsLeave model out to use the server default
429concurrency_limitToo many live sessions for this key. Retry-After is setDelete a session, or wait Retry-After seconds and retry
429mcp_connection_limitToo many open MCP connections for this key: at most twice its concurrency limit. details.limit says how many. Retry-After is setClose MCP clients you no longer use, or wait Retry-After seconds
429connection_limitToo many open connections to one session: 10 on cdp_url, 5 on the live view. details.limit is the cap. Retry-After is setDisconnect a client or close a viewer, then connect again
500internalOur faultSend us the request_id
502proxy_unreachableCould not connect through the proxyCheck the proxy address and credentials, then retry
502session_launch_failedThe browser failed to startRetry
502navigation_failedDNS failure, connection refused, TLS errorCheck the URL, then retry
503capacity_unavailableThe host is full. Retry-After is setWait Retry-After seconds and retry
503residential_unavailableResidential proxy is not configured or not reachableRetry later, or use another proxy type
503agent_unavailableThe server has no model credentials configuredAgent runs are not available on this deployment
504navigation_timeoutThe page did not reach wait_until in timeout_ms, or a start_url did not load in 30 sRaise timeout_ms, or wait for domcontentloaded
504wait_timeoutA wait step timed out. Only inside an /actions resultRaise 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.

CodeWhenWhat to do
max_steps_exceededThe agent needed more than max_steps tool callsRaise max_steps, up to 100, or narrow the task
session_closedThe session ended during the runStart a new run. Raise the session's timeouts if they cut it short
model_errorThe model call failedStart the run again
result_invalidThe result did not match result_schema, or the run ended without oneSimplify the schema, or say in the task what each field should hold
internalOur faultStart the run again. Send us the run ID if it repeats