Skip to main content
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

ClassTypical statusDescription
AuthenticationError401Missing or invalid API key.
ValidationError400Invalid request shape or parameter.
NotFoundError404Browser, resource, or endpoint not found.
ConflictError409Browser is in the wrong state or another operation is in progress.
RateLimitError429Rate limit or quota reached.
PayloadTooLargeError413Request or payload exceeds a limit.
ResourceLimitErrorvariesResource or concurrency limit.
TimeoutError504Browser health or quick-action timeout.
BrowserUnavailableErrorvariesBrowser runtime unavailable, unhealthy, or crashed.
RequestAbortedErrorvariesCaller aborted the request.
ConnectionErrorvariesNetwork connection failure.
InternalError5xxServer-side failure.
BrowserPolicyTipError400Policy-aware navigation produced a blocking policy tip.
WebcomputeErrorvariesBase class for SDK API errors.

​
WebcomputeError fields

FieldDescription
statusCodeHTTP status code.
typeNormalized category.
codeNormalized machine code.
requestIdRequest ID when supplied.
retryableWhether the SDK considers the error retryable.
nextSuggested next action.
paramParameter associated with the failure when known.
detailsRedacted structured details.
helpUrlDocumentation URL for known errors.

​
HTTP status categories

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

​
Gateway error codes

CodeStatusMeaning
INVALID_PARAMS400Invalid request parameters.
UNAUTHORIZED401Missing or invalid Webcompute API key.
BROWSER_NOT_FOUND404Browser does not exist or is no longer available.
SESSION_NOT_FOUND404Legacy/session alias for missing browser state.
BROWSER_WRONG_STATE409Browser is not in a state that supports the operation.
SESSION_WRONG_STATE409Legacy/session alias for wrong browser state.
browser_configuring409Browser is still configuring. Retry after readiness changes.
idempotency_key_reused409Idempotency key was reused with a conflicting request.
operation_in_progress409Another operation is in progress.
RATE_LIMITED429Rate limit reached.
CONCURRENT_LIMIT429Concurrency limit reached.
DAYTONA_ERROR502Upstream sandbox/runtime provider error.
BROWSER_CONFIGURE_FAILED502Browser configuration failed.
BROWSER_HEALTH_TIMEOUT504Browser did not become healthy before timeout.
QUICK_ACTION_TIMEOUT504Ephemeral quick action did not finish before timeout.
INTERNAL_ERROR500Internal 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:
CodeMeaning
BROWSER_LAUNCH_FAILEDChrome could not launch.
BROWSER_CRASHEDBrowser crashed during work.
NAVIGATION_TIMEOUTNavigation exceeded its timeout.
NAVIGATION_FAILEDNavigation failed for a non-timeout reason.
SELECTOR_NOT_FOUNDRequested selector was not found.
CAPTCHA_SOLVE_FAILEDCAPTCHA resolution failed.
PROXY_CONNECTION_FAILEDBrowser could not connect through the configured proxy.
SCREENSHOT_FAILEDScreenshot capture failed.
PDF_FAILEDPDF generation failed.
EXECUTE_FAILEDPlaywright 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:
FieldDescription
successWhether the Playwright code completed.
errorExecution error details.
logsConsole logs captured during execution.
statusCompact runtime status when requested.
observationPage observation when requested.
artifactsScreenshot, 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.