Skip to content

Troubleshooting

Start with the public HTTP status and error code. Avoid collecting secrets or page data while diagnosing an issue.

Authentication fails

  • Confirm the request uses Authorization: Bearer <api-key>.
  • Confirm AIMLIB_BASE_URL is the regional URL assigned to the rental.
  • Check that the key is active and has the endpoint's required scope.
  • If a key may have been exposed, revoke it instead of testing it in more tools.

401 unauthorized means the credential was not accepted. 403 forbidden means the authenticated key lacks a required scope. 403 lease_inactive means the account or device rental does not meet the operation requirement.

No devices are returned

GET /v1/devices returns only active rentals for the authenticated customer. An empty array does not represent the entire fleet. Verify the customer account, rental dates, and regional URL with support.

Proxy connection fails

  1. Fetch the current proxy URL from GET /v1/devices; do not reuse a URL from an older rental.
  2. Test a known working public HTTPS destination that you are authorized to access.
  3. Confirm your client supports the chosen scheme.
  4. For SOCKS5 hostname resolution, try socks5h_url with a compatible client.
  5. Check that the destination hostname resolves and is reachable from another client.

A generic SOCKS failure can represent DNS failure, an unreachable destination, or client configuration. Do not assume it identifies the failing component.

IP rotation remains queued

Use the returned operation ID:

result = await ai.operations.wait(operation_id, timeout=300)

Network operations on one device must be spaced by at least 30 seconds. A failed or timeout result is terminal; wait before retrying and contact support if the same device repeatedly fails.

Browser does not become ready

  • Confirm device.browser_available is true.
  • Confirm the device still has an active rental and proxy.
  • Allow up to the SDK's default 180-second readiness timeout.
  • If creation returns browser_unavailable, use bounded backoff rather than creating sessions in a tight loop.
  • If an earlier session is stopping, wait a few seconds before retrying.

Repeated failures on one device are not expected. File a ticket with the device ID, approximate UTC time, HTTP status, and public error code.

Browser session disappears

A session can end at its TTL, idle timeout, rental end, customer stop request, or an applicable account limit. 404 session_not_found means no active session is available. Create a new session only if the rental remains eligible.

JavaScript application appears empty

Many applications render after the first response. Wait for a meaningful element instead of reading the DOM immediately:

await page.goto("https://example.com", wait_until="domcontentloaded")
await page.wait_for_selector("main")

Use browser-client locators for elements in open shadow roots. Avoid fixed sleeps when a specific state or selector is available.

A browser capability is unavailable

BrowserPolicyError means the requested capability is outside the supported customer browser interface. Confirm the method is documented in the current SDK reference and contact support if a documented method remains unavailable.

Safe support bundle

Include only:

  • Approximate UTC time.
  • Device, session, ticket, or operation ID.
  • HTTP status and public error code.
  • A short sequence of API or SDK method names.
  • Whether a known working public HTTPS destination reproduced the issue.

Do not include API keys, proxy URLs, connection tokens, cookies, headers, full visited URLs, page content, screenshots containing personal data, or form values.