Error codes

Webcompute has two failure layers:

Platform/API failures, which throw SDK errors or return HTTP error envelopes.
Browser-code execution outcomes, where the API request succeeds but browser.playwright.execute(...) returns success: false.

Handle both.

import { WebcomputeError, redactValueForObservability } from "@webcompute/sdk";

try {
  const result = await browser.playwright.execute({ code });

  if (!result.success) {
    console.error(
      "Browser code failed",
      redactValueForObservability({
        code: result.error?.code,
        name: result.error?.name,
        message: result.error?.message,
      }),
    );
  }
} catch (error) {
  if (error instanceof WebcomputeError) {
    console.error(error.statusCode, error.code, error.next);
  }
}

Log selected, redacted fields from browser-code errors. Avoid serializing the full result.error object by default because error messages and stacks can include page content, request fragments, response fragments, local paths, or other sensitive context.

SDK error classes

Class	Typical status	Description
`AuthenticationError`	`401`	Missing or invalid API key.
`ValidationError`	`400`	Invalid request shape or parameter.
`NotFoundError`	`404`	Browser, resource, or endpoint not found.
`ConflictError`	`409`	Browser is in the wrong state or another operation is in progress.
`RateLimitError`	`429`	Rate limit or quota reached.
`PayloadTooLargeError`	`413`	Request or payload exceeds a limit.
`ResourceLimitError`	varies	Resource or concurrency limit.
`TimeoutError`	`504`	Browser health or quick-action timeout.
`BrowserUnavailableError`	varies	Browser runtime unavailable, unhealthy, or crashed.
`RequestAbortedError`	varies	Caller aborted the request.
`ConnectionError`	varies	Network connection failure.
`InternalError`	`5xx`	Server-side failure.
`BrowserPolicyTipError`	`400`	Policy-aware navigation produced a blocking policy tip.
`WebcomputeError`	varies	Base class for SDK API errors.

`WebcomputeError` fields

Field	Description
`statusCode`	HTTP status code.
`type`	Normalized category.
`code`	Normalized machine code.
`requestId`	Request ID when supplied.
`retryable`	Whether the SDK considers the error retryable.
`next`	Suggested next action.
`param`	Parameter associated with the failure when known.
`details`	Redacted structured details.
`helpUrl`	Documentation URL for known errors.

HTTP status categories

Status	Meaning
`400`	Invalid request shape or parameter.
`401`	Missing or invalid API key.
`403`	Permission denied.
`404`	Browser, resource, or endpoint not found.
`409`	Browser not ready, invalid lifecycle transition, idempotency conflict, or operation in progress.
`413`	Payload too large.
`429`	Rate limit or resource limit reached.
`500`	Internal platform error.
`502`	Upstream/browser configuration failure.
`503`	Service unavailable.
`504`	Timeout.

Gateway error codes

Code	Status	Meaning
`INVALID_PARAMS`	`400`	Invalid request parameters.
`UNAUTHORIZED`	`401`	Missing or invalid Webcompute API key.
`BROWSER_NOT_FOUND`	`404`	Browser does not exist or is no longer available.
`SESSION_NOT_FOUND`	`404`	Legacy/session alias for missing browser state.
`BROWSER_WRONG_STATE`	`409`	Browser is not in a state that supports the operation.
`SESSION_WRONG_STATE`	`409`	Legacy/session alias for wrong browser state.
`browser_configuring`	`409`	Browser is still configuring. Retry after readiness changes.
`idempotency_key_reused`	`409`	Idempotency key was reused with a conflicting request.
`operation_in_progress`	`409`	Another operation is in progress.
`RATE_LIMITED`	`429`	Rate limit reached.
`CONCURRENT_LIMIT`	`429`	Concurrency limit reached.
`DAYTONA_ERROR`	`502`	Upstream sandbox/runtime provider error.
`BROWSER_CONFIGURE_FAILED`	`502`	Browser configuration failed.
`BROWSER_HEALTH_TIMEOUT`	`504`	Browser did not become healthy before timeout.
`QUICK_ACTION_TIMEOUT`	`504`	Ephemeral quick action did not finish before timeout.
`INTERNAL_ERROR`	`500`	Internal platform failure.

The SDK normalizes some legacy codes into current error codes such as invalid_request, authentication_failed, browser_not_found, operation_in_progress, rate_limited, quota_exceeded, payload_too_large, upstream_timeout, internal_error, browser_unavailable, and operation_cancelled.

Browser-server error codes

Browser-code execution and quick actions may surface browser-server codes:

Code	Meaning
`BROWSER_LAUNCH_FAILED`	Chrome could not launch.
`BROWSER_CRASHED`	Browser crashed during work.
`NAVIGATION_TIMEOUT`	Navigation exceeded its timeout.
`NAVIGATION_FAILED`	Navigation failed for a non-timeout reason.
`SELECTOR_NOT_FOUND`	Requested selector was not found.
`CAPTCHA_SOLVE_FAILED`	CAPTCHA resolution failed.
`PROXY_CONNECTION_FAILED`	Browser could not connect through the configured proxy.
`SCREENSHOT_FAILED`	Screenshot capture failed.
`PDF_FAILED`	PDF generation failed.
`EXECUTE_FAILED`	Browser-code execution failed.

Retry behavior

Default SDK retries apply to:

HTTP status 429, 500, 502, 503, and 504.
Network connection errors.

Default retry config is:

{
  maxRetries: 3,
  initialIntervalMs: 500,
  maxIntervalMs: 30000,
  exponent: 1.5,
  jitter: true,
  retryableStatusCodes: [429, 500, 502, 503, 504],
  retryConnectionErrors: true
}

Do not retry blindly when next is change_request, authenticate, or abort.

Browser-code failures

browser.playwright.execute(...) can return success: false while the HTTP request succeeds. Inspect:

Field	Description
`success`	Whether the browser code completed.
`error`	Execution error details.
`logs`	Console logs captured during execution.
`status`	Compact runtime status when requested.
`observation`	Page observation when requested.
`artifacts`	Screenshot, recording, or generated-file artifacts.

Use platform errors for request-level failures and execution fields for in-browser failures.

Common cases

Browser health timeout

The browser did not become healthy before the operation timeout. What to do:

Check browser.status().
Retry with a fresh browser when appropriate.
Inspect Debug UI or recordings when the browser is repeatedly blocked or unhealthy.
Increase timeouts only when the page is expected to be slow.

Quick action timeout

The quick action did not finish before its timeout. What to do:

Add waitFor only for the selector you need.
Reduce output size with maxChars or selector.
Move login-state or multi-step workflows to a managed browser.
Use web.agent() or SDK agent sessions when the task needs planning and repeated observation.

Proxy connection failed

The browser could not connect through the configured proxy. What to do:

Verify the proxy URL and credentials.
Test proxy reachability outside the agent prompt.
Keep proxy credentials in environment variables.
Confirm the surface you are using actually supports proxy options. See Proxy reference.

Get started

Build agent workflows

Observe and debug

Runtime concepts

Examples

Integrations

Production

Reference

API reference

SDK error classes

`WebcomputeError` fields

HTTP status categories

Gateway error codes

Browser-server error codes

Retry behavior

Browser-code failures

Common cases

Browser health timeout

Quick action timeout

Proxy connection failed

​SDK error classes

​WebcomputeError fields

​HTTP status categories

​Gateway error codes

​Browser-server error codes

​Retry behavior

​Browser-code failures

​Common cases

​Browser health timeout

​Quick action timeout

​Proxy connection failed

SDK error classes

`WebcomputeError` fields

HTTP status categories

Gateway error codes

Browser-server error codes

Retry behavior

Browser-code failures

Common cases

Browser health timeout

Quick action timeout

Proxy connection failed