> ## Documentation Index
> Fetch the complete documentation index at: https://docs-preview.webcompute.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Error codes

> Understand Webcompute SDK errors, Gateway error codes, browser-server failures, retry behavior, and browser-code execution outcomes.

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.

```ts theme={null}
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:

```ts theme={null}
{
  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](/reference/proxy-reference).