Limits and errors¶

This page summarizes customer-visible limits and stable public error codes. Account-specific limits can differ; values returned by the API take precedence.

Default limits¶

Limit	Default or range
Customer API requests	6,000 per API key per hour
Remote-browser session TTL	Up to 30 minutes and never past rental end
Remote-browser idle timeout	120 seconds by default
Browser sessions per device	Normally one
Tabs per session	Returned as `max_tabs`; normally five
Network-operation spacing	At least 30 seconds per device
Request body	Up to 1 MiB

Usage allowances can apply per device and session. Contact support for limits assigned to your account.

HTTP status guidance¶

Status	Action
`400`	Correct the request; do not retry unchanged
`401`	Replace or revoke the customer key
`403`	Verify account state, active rental, and key scopes
`404`	Treat the resource as unavailable to this account
`409`	Resolve the reported state conflict before retrying
`429`	Respect `Retry-After` or the documented operation spacing
`500`	Retry with bounded exponential backoff; contact support if persistent
`503`	Retry with bounded backoff because the service or browser is temporarily unavailable

Use jitter and cap retries. Never retry browser creation indefinitely; doing so can create duplicate work or prolong an account-capacity issue.

Stable error codes¶

Code	Typical status	Meaning
`unauthorized`	401	Customer key is missing, invalid, expired, or revoked
`forbidden`	403	Customer key lacks the required scope
`lease_inactive`	403	The active-rental requirement is not met
`session_not_found`	404	No active browser session exists for the device
`operation_not_found`	404	Operation is invalid, unsupported, no longer eligible, or not owned by the caller
`ticket_not_found`	404	Ticket is unavailable to the caller
`browser_unavailable`	409 or 503	Remote browser is not currently available
`data_cap_exceeded`	409	The account's usage allowance is exhausted
`no_session`	409	Start a browser session before changing its footprint
`capacity_unavailable`	429 or 503	Browser capacity is currently unavailable
`rate_limited`	429	Request or network operation was issued too quickly
`footprint_not_clean`	400	Footprint selection is not available for the selected device
`bad_carrier`	400	Carrier identifier is not accepted
`operation_failed`	200 operation result	Network operation did not complete successfully
`operation_timeout`	200 operation result	Network operation did not finish before its service timeout

Human-readable message values can improve logs shown to an operator, but they are not a versioned contract. Branch on HTTP status and error.

Backoff example¶

import asyncio
import random

for attempt in range(5):
    try:
        session = await device.browser(ttl="10m")
        break
    except BrowserUnavailableError:
        if attempt == 4:
            raise
        await asyncio.sleep(min(2 ** attempt + random.random(), 15))

Do not apply this pattern to 400, authentication failures, or another non-retryable response.

Credential-safe diagnostics¶

When filing a ticket, include:

Approximate UTC time.
Device ID and session or operation ID when available.
HTTP status and public error code.
Whether the issue is reproducible on a known working authorized destination.

Remove API keys, proxy credentials, connection tokens, full authenticated URLs, cookies, headers, page content, and personal data.