Limites e erros
Os limites das sessões hospedadas, os erros que a API retorna e quais deles valem uma nova tentativa.
Limites
- 75 navegadores rodando ou iniciando ao mesmo tempo por conta.
- As sessões duram no máximo 4 horas.
- Uma sessão sem nenhum comando CDP por 5 minutos é fechada (altere isso com
idleTimeoutSec). - Toda sessão começa com um perfil de navegador novo, apagado quando a sessão termina, a menos que você use um perfil com nome, que guarda os cookies e o armazenamento dos sites entre sessões.
- Por segurança, o navegador não pode abrir arquivos locais (
file://), fazer upload de arquivos a partir do servidor, acessar redes privadas ou internas nem enviar e-mail pela porta 25. - Fazer upload de um arquivo funciona a partir do seu código — veja Enviando arquivos. Os downloads ficam no nosso servidor e são apagados junto com a sessão; para guardar um arquivo, busque-o de dentro da página e retorne o conteúdo dele.
- Não é possível carregar extensões do Chrome em navegadores hospedados.
- O navegador não repassa mensagens do console nem erros da página, então
page.on("console")epage.on("pageerror")ficam em silêncio. Colete o que precisar dentro da página e leia de volta comevaluate. Duas chamadas do driver dependem desses eventos: veja setContent e exposeFunction.
Erros
| Status | 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. |
Os erros vêm em JSON: { "error": "...", "code": "..." }. Se a própria conexão WebSocket for recusada, crie uma nova sessão: as URLs de conexão são de uso único e expiram após dois minutos. Um upgrade de WebSocket recusado responde com um status HTTP e um error em JSON: 409 quando a URL já foi usada, a sessão foi cancelada, não foi iniciada com keepAlive ou já está conectada; 401 quando a URL expirou.
O que tentar de novo
- Tente de novo com backoff:
503 NO_CAPACITYe503 NO_WORKER(espere 1, 2, 4… segundos com um pouco de jitter e desista depois de algumas tentativas), e um429sem código (o rate limit por endereço). - Tente algumas vezes com backoff: outras respostas
5xxe uma conexão recusada antes de o seu script começar (com uma nova sessão: a URL de conexão antiga já foi gasta). - Nunca em loop:
400(corrija a requisição),401,402(adicione crédito),429 CONCURRENCY_LIMIT(feche um navegador antes) e409 PROFILE_IN_USE. Alguém precisa agir; tentar de novo só queima requisições.