制限とエラー
ホスト型セッションの制限、API が返すエラー、そのうちリトライする価値のあるものを説明します。
制限
- 1 アカウントあたり、同時に実行中または起動中にできるブラウザは 75 個までです。
- セッションの最長時間は 4 時間です。
- CDP コマンドが 5 分間送られないセッションは閉じられます（
idleTimeoutSecで変更できます）。 - 名前付きのプロファイル（セッション間で Cookie やサイトストレージを保持します）を使わない限り、各セッションは新しいブラウザプロファイルで始まり、そのプロファイルはセッション終了時に削除されます。
- 安全のため、ブラウザはローカルファイル（
file://）を開くこと、サーバー上のファイルをアップロードすること、プライベートネットワークや内部ネットワークにアクセスすること、ポート 25 でメールを送信することができません。 - ファイルのアップロードはお使いのコードから行えます。ファイルのアップロードを参照してください。ダウンロードは当社のサーバー上に残り、セッションとともに削除されます。ファイルを残したい場合は、ページ内から取得して、その内容を返してください。
- ホスト型ブラウザには Chrome 拡張機能を読み込めません。
- ブラウザはコンソールメッセージやページエラーを転送しないため、
page.on("console")とpage.on("pageerror")には何も届きません。必要な情報はページ内で収集し、evaluateで読み出してください。これらのイベントに依存するドライバーの呼び出しが 2 つあります。setContent と exposeFunction を参照してください。
エラー
| ステータス | code | 説明 |
|---|---|---|
| 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. |
エラーは JSON 形式で返ります（{ "error": "...", "code": "..." }）。WebSocket 接続そのものが拒否された場合は、新しいセッションを作成してください。接続 URL は 1 回限りで、2 分後に失効します。WebSocket のアップグレードが拒否された場合は、HTTP ステータスと JSON の error が返ります。URL が使用済みの場合、セッションがキャンセルされた場合、keepAlive なしで起動された場合、すでに接続済みの場合は 409、URL の有効期限が切れている場合は 401 です。
リトライすべきもの
- バックオフ付きでリトライする：
503 NO_CAPACITYと503 NO_WORKER（多少のジッターを加えながら 1、2、4… 秒と待ち、数回で諦めます）、およびコードのない429（アドレス単位のレート制限）。 - バックオフ付きで数回だけリトライする：その他の
5xxレスポンスと、スクリプトの開始前に拒否された接続（新しいセッションで行います。古い接続 URL は使用済みです）。 - ループでリトライしない：
400（リクエストを修正します）、401、402（クレジットを追加します）、429 CONCURRENCY_LIMIT（先にブラウザを閉じます）、409 PROFILE_IN_USE。人が対処する必要があり、リトライしてもリクエストを無駄にするだけです。