跳到正文

限制与错误

托管会话的限制、API 返回的错误,以及其中哪些值得重试。

限制

  • 每个账号最多同时有 75 个浏览器处于运行或启动状态。
  • 会话最长持续 4 小时。
  • 连续 5 分钟没有任何 CDP 命令的会话会被关闭(可通过 idleTimeoutSec 修改)。
  • 每个会话都从一个全新的浏览器 Profile 开始,并在会话结束时删除;除非你使用命名的 Profile,它会在会话之间保留 cookie 和站点存储。
  • 出于安全考虑,浏览器不能打开本地文件(file://)、不能从服务器上传文件、不能访问私有或内部网络,也不能通过 25 端口发送邮件。
  • 从你的代码上传文件是可行的——参见上传文件。下载的文件保存在该会话自己的文件夹中,并随会话一起删除;请通过你的连接取回,参见下载文件。
  • 每个会话的文件夹最多容纳 1 GB,下载的文件和你放入的文件合计。浏览器下载超过这个量时,会话会以原因 max_files_size 结束。
  • 托管浏览器无法加载 Chrome 扩展。
  • 浏览器不会转发控制台消息或页面错误,因此 page.on("console") 和 page.on("pageerror") 都不会收到任何内容。请在页面内收集你需要的信息,再用 evaluate 读回。有两个驱动调用依赖这些事件:参见 setContent 和 exposeFunction。

错误

状态码code含义
400—The body is not JSON, or an option is invalid; the message says which.
400UNKNOWN_VERSIONNo release matches version; the message lists the ones you can pick.
400TOO_LARGEThe whole run configuration as stored (task, schema, sealed secrets and the browser options) is capped at 60 KB; shorten them.
400INVALIDA webhook or cookie import body is invalid; the message says which field (and which cookie).
400TOO_MANYA cookie import would leave the profile with more than 5000 cookies. Use mode "replace", or import fewer.
400CHALLENGE_KEY_MISSINGchallengeService 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.
401INVALID_LINKA share, hand-off or replay link that is invalid, of the wrong kind, or expired.
403SUSPENDEDCloud browsers are suspended for this account (no new sessions or runs); contact support@clearcotelabs.com.
403NOT_CONTROLOnly a link that lets you take control can mark a hand-off done; this one is watch-only.
402INSUFFICIENT_BALANCEBalance below the minimum. Top up in the dashboard.
402CHALLENGE_LIMITThis month's challenge-service limit on our key is reached. Raise it in the dashboard (Settings), or use your own key.
404NOT_FOUNDNo session, run, profile, webhook or recording with that id on your account.
409NOT_RUNNINGLive view, a reconnect or a hand-off asked for before the browser started or after it ended.
409NOT_KEEPALIVEThis session cannot be reconnected. Start it with keepAlive: true.
409PROFILE_IN_USEAnother session is already saving to that profile. Stop it, or open the profile with persist: false.
409NOT_READYThe recording is still being uploaded. Try again shortly after the session ends.
409HANDOFF_UNSUPPORTEDThe server running this browser does not support hand-off yet.
409NO_HANDOFFMarked done, but no hand-off was asked for.
409HANDOFF_EXPIREDThe hand-off timed out before it was marked done.
409WEBHOOK_LIMITAt most 5 webhooks per account. Delete one first.
410ENDEDA live link whose session has ended.
410GONEA replay link whose recording is no longer available (failed, or past its retention).
413TOO_LARGEA cookie import would make the profile larger than 3.5 MB.
429CONCURRENCY_LIMITToo 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.
503NO_CAPACITYNo free browser slot right now, or no server that can run what you asked for (runs, schema, secrets, recording, the challenge service). Answered at once, with a Retry-After header and retryAfterSec (2 to 30) in the body: retry after that many seconds. queue.waiting is how many browsers wait to start across all servers.
503NO_WORKERThe server running that session is not reachable at the moment.
503NOT_CONFIGUREDHosted browsers (or that part of them) are not configured on this server.
503NOT_AVAILABLENotes, profiles, runs, recordings, events, hand-off, webhooks or the challenge service are not enabled on this server yet.

错误以 JSON 形式返回:{ "error": "...", "code": "..." }。如果 WebSocket 连接本身被拒绝,请创建一个新会话:连接 URL 是一次性的,45 秒后过期。被拒绝的 WebSocket 升级请求会返回一个 HTTP 状态码和一个 JSON error:URL 已被使用、会话已取消、会话启动时未设置 keepAlive 或已有客户端连接时,返回 409;URL 已过期时,返回 401。

哪些错误该重试

  • 带退避重试:503 NO_CAPACITY 和 503 NO_WORKER(依次等待 1、2、4… 秒并加入一些随机抖动,重试几次后放弃),以及不带 code 的 429(按地址的速率限制)。NO_CAPACITY 会立即返回,并告诉你需要等待多久:见它的 Retry-After 响应头和 retryAfterSec(2 到 30 秒,取决于有多少浏览器正在等待启动);当它比你自己的等待时间更长时,就按它来等待。
  • 带退避重试少数几次:其他 5xx 响应,以及在你的脚本开始运行之前就被拒绝的连接(需使用新会话:旧的连接 URL 已经作废)。
  • 切勿循环重试:400(修正请求)、401、402(充值)、429 CONCURRENCY_LIMIT(先关闭一个浏览器)和 409 PROFILE_IN_USE。这些都需要人来处理;重试只会白白消耗请求。