Límites y errores

Los límites de las sesiones alojadas, los errores que devuelve la API y cuáles vale la pena reintentar.

Límites

75 navegadores en ejecución o iniciándose a la vez por cuenta.
Las sesiones duran como máximo 4 horas.
Una sesión sin ningún comando CDP durante 5 minutos se cierra (puedes cambiarlo con idleTimeoutSec).
Cada sesión empieza con un perfil de navegador nuevo, que se borra cuando termina la sesión, a menos que uses un perfil con nombre, que conserva las cookies y el almacenamiento de los sitios entre sesiones.
Por seguridad, el navegador no puede abrir archivos locales (file://), subir archivos desde el servidor, acceder a redes privadas o internas, ni enviar correo por el puerto 25.
Subir un archivo funciona desde tu código: consulta Subir archivos. Las descargas se quedan en nuestro servidor y se borran junto con la sesión; para conservar un archivo, obtenlo desde dentro de la página y devuelve su contenido.
No se pueden cargar extensiones de Chrome en los navegadores alojados.
El navegador no reenvía los mensajes de consola ni los errores de página, así que page.on("console") y page.on("pageerror") no reciben nada. Recoge lo que necesites dentro de la página y léelo con evaluate. Dos llamadas del driver dependen de esos eventos: consulta setContent y exposeFunction.

Errores

Estado	code	Significado
400	—	The body is not JSON, or an option is invalid; the message says which.
400	`UNKNOWN_VERSION`	No release matches `version`; the message lists the ones you can pick.
400	`TOO_LARGE`	The whole run configuration as stored (task, schema, sealed secrets and the browser options) is capped at 60 KB; shorten them.
400	`INVALID`	A webhook or cookie import body is invalid; the message says which field (and which cookie).
400	`TOO_MANY`	A cookie import would leave the profile with more than 5000 cookies. Use mode "replace", or import fewer.
400	`CHALLENGE_KEY_MISSING`	challengeService has no key to use: pass challengeService.apiKey, store your key in the dashboard (Settings), or use key "managed".
401	—	Missing, malformed or revoked API key.
401	`INVALID_LINK`	A share, hand-off or replay link that is invalid, of the wrong kind, or expired.
403	`NOT_CONTROL`	Only a link that lets you take control can mark a hand-off done; this one is watch-only.
402	`INSUFFICIENT_BALANCE`	Balance below the minimum. Top up in the dashboard.
402	`CHALLENGE_LIMIT`	This month's challenge-service limit on our key is reached. Raise it in the dashboard (Settings), or use your own key.
404	`NOT_FOUND`	No session, run, profile, webhook or recording with that id on your account.
409	`NOT_RUNNING`	Live view, a reconnect or a hand-off asked for before the browser started or after it ended.
409	`NOT_KEEPALIVE`	This session cannot be reconnected. Start it with keepAlive: true.
409	`PROFILE_IN_USE`	Another session is already saving to that profile. Stop it, or open the profile with persist: false.
409	`NOT_READY`	The recording is still being uploaded. Try again shortly after the session ends.
409	`HANDOFF_UNSUPPORTED`	The server running this browser does not support hand-off yet.
409	`NO_HANDOFF`	Marked done, but no hand-off was asked for.
409	`HANDOFF_EXPIRED`	The hand-off timed out before it was marked done.
409	`WEBHOOK_LIMIT`	At most 5 webhooks per account. Delete one first.
410	`ENDED`	A live link whose session has ended.
410	`GONE`	A replay link whose recording is no longer available (failed, or past its retention).
413	`TOO_LARGE`	A cookie import would make the profile larger than 3.5 MB.
429	`CONCURRENCY_LIMIT`	Too many browsers running or starting at once. Close one first.
429	—	More than 60 create calls in a minute from one address. Slow down.
429	—	More than 60 cookie imports in 10 minutes on one account (or 30 new webhooks in 10 minutes, 10 webhook tests or 60 hand-off requests a minute). Wait and retry.
503	`NO_CAPACITY`	No free browser slot right now, or no server that can run what you asked for (runs, schema, secrets, recording, the challenge service). Retry after a few seconds.
503	`NO_WORKER`	The server running that session is not reachable at the moment.
503	`NOT_CONFIGURED`	Hosted browsers (or that part of them) are not configured on this server.
503	`NOT_AVAILABLE`	Notes, profiles, runs, recordings, events, hand-off, webhooks or the challenge service are not enabled on this server yet.

Los errores son JSON: { "error": "...", "code": "..." }. Si se rechaza la conexión WebSocket en sí, crea una sesión nueva: las URLs de conexión son de un solo uso y vencen a los dos minutos. Un upgrade de WebSocket rechazado responde con un estado HTTP y un error en JSON: 409 cuando la URL ya se usó, la sesión se canceló, no se inició con keepAlive o ya tiene un cliente conectado; 401 cuando la URL venció.

Qué reintentar

Reintenta con backoff: 503 NO_CAPACITY y 503 NO_WORKER (espera 1, 2, 4… segundos con algo de jitter y abandona después de unos pocos intentos), y un 429 sin código (el límite de tasa por dirección).
Reintenta unas pocas veces con backoff: otras respuestas 5xx, y una conexión que se rechazó antes de que arrancara tu script (con una sesión nueva: la URL de conexión anterior ya se usó).
Nunca en bucle: 400 (corrige la solicitud), 401, 402 (agrega crédito), 429 CONCURRENCY_LIMIT (cierra primero un navegador) y 409 PROFILE_IN_USE. Tiene que intervenir una persona; reintentar solo quema solicitudes.