2.1 The signature: two arguments, two TypeErrors, one boolean

Basic

The signature of sendBeacon() is small enough to memorize and sharp enough to cut you if you memorize it wrong. This page walks through every value the second argument can take, the exactly two conditions that throw, and the one condition that returns false — each demonstrated live, because the runnable example below triggers the real TypeErrors in a real browser frame.

The real IDL — two parameters, not three

The complete IDL met you in part one: sendBeacon(url, data) — a URL, an optional body, one boolean back, nothing else. There is no third parameter. No options bag, no configuration object, no way to choose a method or set headers. If you have seen code like sendBeacon(url, data, {method: 'POST'}) — including in quiz questions — that API has never existed in any published version of the specification, from the 2013 First Public Working Draft to the current draft. Everything the request will be is decided by the fixed recipe you met in part one.

The first parameter is a USVString URL, parsed against the document's base URL like any relative reference — '/api/collect' is the ordinary form. The second is the Fetch standard's BodyInit union (or null, which is also the default when you omit it). That union quietly accepts more than most tutorials admit, and rejects exactly one member at runtime — both covered in the next section of the series.

The two TypeErrors

The spec defines precisely two throwing conditions, and the runnable example triggers both for real. First: the URL must parse, and its scheme must be http or https — anything else throws TypeError synchronously, before any data is queued. Second: although ReadableStream is technically part of BodyInit, the Fetch standard's body-extraction algorithm throws a TypeError for stream bodies whenever keepalive is true — and beacons always set it. A stream can never be re-sent after the page dies, so the platform refuses to pretend otherwise.

Everything else returns a boolean — even calls that look like mistakes. No data at all is a legitimate body-less POST. A number, a plain object, or an array does not throw either: Web IDL union conversion has a string catch-all, so sendBeacon(url, 42) happily ships the string "42". The next page in the series shows exactly what the platform does to those odd values, using the same extraction machinery a Request uses.

What false means — and what it never means

false has exactly one cause: the body did not fit the in-flight keepalive quota — the 64 KiB pool the Fetch standard enforces and this series devotes a full page to. It is a capacity signal, synchronous and honest: when it comes back, no bytes have touched the network, and no server has been contacted. And true, as part one established, reports queueing only — the transfer happens entirely in the background, and its outcome is invisible to your code by design.

navigator.sendBeacon('/api/collect', ?);