lupin.Open console
Browsers

Retry browser work without repeating unknown effects

Classify validation, permission, provider and uncertain-action failures before deciding what can be retried.

Lupin editorialAI-assisted3 min read

Classify the failure before choosing recovery

A failed browser request can mean invalid input, insufficient authority, unavailable infrastructure, an ended session, a page problem or an unknown action outcome. These conditions need different responses. Start with the machine-readable error code and the last confirmed session and page state. Retrying every error with exponential backoff is inappropriate when a click might already have submitted a form. Equally, immediately allocating a new browser can duplicate a paid resource whose creation response was lost. Keep transport reliability separate from the meaning and side effects of the operation you sent.

Fix deterministic rejections directly

invalid_browser_action means the input does not match the fixed action catalog. public_url_required points to the public-site boundary, while workspace_key_required indicates the wrong key scope. browsers_not_configured is an operator readiness issue. None becomes valid by waiting a few seconds. Validate the URL, selector and arguments against the shared contract, and use a human-verified organization key with the required permissions. If the bootstrap key is the only available credential, the agent can explain the missing authorization but cannot grant it to itself. These errors should stop dependent page work until the underlying cause changes.

Preserve idempotency across transport retries

Browser mutations use a stable Idempotency-Key tied to the action path and input. A completed operation can return its stored result, while a different payload under the same key conflicts. A running or failed prior attempt can return browser_action_uncertain because the server will not replay an unknown effect. Keep that key in the task record. Do not rotate it automatically to make a retry look new. Instead, read the current page and determine whether the intended transition happened. A new key is appropriate only for a consciously chosen new action after that reconciliation.

Illustrative request; source reviewed, not executed against a live provider.
{"action":"read","tab_id":"TARGET_ID_FROM_TABS"}

Reconcile resources before replacement

session_ended means the existing browser cannot continue, and a new authorized session begins without the previous cookies. browser_provider_changed means the stored resource belongs to a previous provider. A generic browser_provider_error can reflect upstream failure without proving closure. Inspect the known resource and allocation outcome before creating another session. Provider capacity or runtime budget failures also require respecting the returned policy. If an end request failed, preserve cleanup uncertainty in the task result. A replacement browser does not settle the old session's runtime or close an unresolved resource.

Use observations to justify the next attempt

For navigation or selector failures, obtain a fresh tab inventory and page read where available. Compare the observed URL, visible controls and confirmation state to the expected result. If the action remains ambiguous, ask for an authorized human handoff rather than guessing. Record the sanitized error, operation identity, observation and chosen recovery so a reviewer can understand why another attempt was safe. Once the task finishes or stops, end the browser and verify cleanup separately. A retry policy is dependable when it reduces uncertainty before repeating effects, not merely when it eventually receives an HTTP success.

Sources & verification

Reviewed against the current Lupin route, provider adapter and shared input contracts, plus the linked official references. Examples were not run against live services.

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.

Put it into practice

Give your agent the right tools.

Review the API, workspace requirements and permissions before enabling a workflow.

Explore browsers