The short answer: Playwright raises TimeoutError when an action outlasts its limit: 30 seconds by default for actions like click(), wait_for() and goto(). The message names the call, as in Page.goto: Timeout 5000ms exceeded. or Locator.click: Timeout 3000ms exceeded., which tells you whether the page or one element was slow. Import TimeoutError from playwright.sync_api to catch it. Set one limit for the page with set_default_timeout(), load with wait_until="domcontentloaded", and wait for the element you need. When you would rather not run a browser at all, our API runs the same wait in our Chrome, and a call that runs out of time costs nothing.
What Playwright does on a slow server
Start a listener in one terminal with nc -lk 8799. It takes each connection and never answers, like a server that hangs. Run this in a second terminal:
import time
from playwright.sync_api import TimeoutError, sync_playwright
with sync_playwright() as p:
page = p.chromium.launch().new_page()
t = time.monotonic()
try:
page.goto("http://127.0.0.1:8799/", timeout=5000)
except TimeoutError as err:
print(type(err).__name__, "|", str(err).splitlines()[0], "| after", round(time.monotonic() - t, 1), "s")TimeoutError | Page.goto: Timeout 5000ms exceeded. | after 5.0 s
Page.gotoin the message says the page itself never loaded. The browser sent its request;ncnever answered.gotowaits for theloadevent by default. A page that loads but keeps fetching ads can hit the limit too.
How Playwright reports a timeout
Our test store answers fast, so give it a limit too short to meet. The error is the same one a slow site gives you:
from playwright.sync_api import TimeoutError, sync_playwright
with sync_playwright() as p:
page = p.chromium.launch().new_page()
page.goto("https://lab.megalania.io/new-arrivals/")
try:
page.locator("#item-99").click(timeout=3000)
except TimeoutError as err:
print(str(err).splitlines()[0])
print("cards on the page:", page.locator("#arrivals li").count())Locator.click: Timeout 3000ms exceeded. cards on the page: 12
Locator.clickin the message says the page was fine and one element was not there: 12 cards, no#item-99.- A locator waits for its element before it acts. A wrong selector looks like a slow page until you read which call timed out.
The free fix: timeouts and retries
Set a limit on every request, and retry a few times with a pause. This fixes servers that are slow now and then:
import time
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
page = p.chromium.launch().new_page()
page.set_default_timeout(20000)
t = time.monotonic()
page.goto("https://lab.megalania.io/new-arrivals/", wait_until="domcontentloaded")
cards = page.locator("#arrivals li")
cards.nth(11).wait_for()
print(cards.count(), "cards in", round(time.monotonic() - t, 2), "s |", cards.nth(0).locator(".price").inner_text())12 cards in 1.0 s | $112.00
cards.nth(11).wait_for()waits for the 12th card, socount()runs after the list is drawn.set_default_timeout(20000)covers every action on the page.set_default_navigation_timeout()setsgotoon its own.
The fix that climbs: our API
Send the page to our API instead. We fetch it, run a real Chrome when you ask, and an answer that runs out of time costs nothing:
# Run: MEG_API_KEY=YOUR_KEY python fetch.py '#item-12'
import os
import sys
import requests
r = requests.post(
"https://get.megalania.io/v1",
headers={"Authorization": f"Bearer {os.environ['MEG_API_KEY']}"},
json={"url": "https://lab.megalania.io/new-arrivals/", "engine": "browser", "actions": f"wait_for:{sys.argv[1]}", "response_types": "markdown", "timeout": 20},
timeout=100,
)
print(r.status_code, r.headers.get("X-Route", "-"), "credits", r.headers.get("X-Credits-Charged", 0), "|", r.text.count("\n- "), "list items")
print(r.text[:120])200 browser/datacenter credits 18 | 12 list items # New arrivals This page is a JavaScript demo. Your browser draws the list below from the store’s public Store API. A p
wait_for:#item-12is the same wait asfix.py, run in our Chrome. The list came back as 12 Markdown list items.- 18 credits: 15 for the browser and 3 for the wait. Markdown is included, so no JSON credit.
The same call on a page whose list never finishes loading, with a 20-second limit:
MEG_API_KEY=YOUR_KEY python fetch.py '#item-99'
422 - credits 0 | 0 list items
{"error":{"code":"action_failed","field":"actions","message":"actions entry 0 could not run: no visible element matched- Our Chrome met the same missing element as
seen.py, and we answered422action_failedwhen the time for actions ran out. - The message suggests the fix: check the selector, add a wait before it, or raise
timeout.
One honest note: our test store is fast, so these runs show a short limit or a page that never gets ready, not a slow site. On a slow site, the call is the same; the price depends on the route that worked, and our MCP tool check_site tells you that price for free.
What it costs
| What we ran | Route | Credits |
|---|---|---|
| The new arrivals page as Markdown, in the browser | c:dc | 18 |
| The same page waiting for an element that never appears | c:dc | 0 |
sends.py, seen.py and fix.py, in your own Chromium | none | 0 |
Every rule is in Credits. Plans are on the pricing page.
How we measured: Playwright 1.65.2 for Python with its Chrome headless shell 159, Python 3.13.5, one Linux server, 17 Nov 2026. nc -lk 8799 (OpenBSD netcat) as a server that never answers. Our test store for the missing element and for fix.py. Our API on our dev cluster for fetch.py, against the same store on our dev domain. The outputs are copied from those runs.
Limits
- Public pages only. We do not log in, and we do not solve CAPTCHAs. When a page needs either, we stop and say so, for free.
- A page built by JavaScript needs
engine=browser. It costs more. See How to scrape JavaScript-rendered pages. - Slow can mean slow down. A site that answers slowly may be under load. Keep your rate low, fetch public pages only, and follow the site's terms and robots.txt.
What to do when a site answers 429 instead is in 429 Too Many Requests when scraping.