--- title: Errors and node readiness description: Handle window.swarm and window.radicle errors in a Freedom dapp: user rejections, missing grants, node not ready, limits, and when to retry. kick: Overview dek: Errors carry an EIP-1193-style code and usually a data.reason. Most failures fall into four groups, and only some are worth retrying. --- Every rejection is an `Error` with `code`, `message` and, for most validation and node failures, `data.reason`. ```javascript async function call(method, params) { try { return await window.swarm.request({ method, params }); } catch (err) { switch (err.code) { case 4001: // the user said no throw err; case 4100: // a grant is missing: data.reason says which await window.swarm.requestAccess(); return window.swarm.request({ method, params }); case 4900: // node not available if (err.data?.reason === 'node-stopped' || err.data?.reason === 'node-not-ready') { await new Promise((r) => setTimeout(r, 3000)); return window.swarm.request({ method, params }); } throw err; default: throw err; } } } ``` A real app should cap retries and back off; this only shows the shape. ## The four groups **The user decided (`4001`).** Stop. Ask again only on a new user action. A declined [manifest sheet](swarm.html.md#permission-manifests) stays declined until the page reloads, so tell the user to reload rather than calling `requestAccess` in a loop. **A grant is missing (`4100`).** `not_connected`, `feed_not_granted` or `messaging_not_granted`. Call `requestAccess`, or the tier's first method, to show the prompt. A `4100` also tells you the user disconnected your origin. **The node is not ready (`4900`).** `data.reason` says why: - `node-stopped`: the node is not running or not answering. It also happens for a short while right after the user unlocks, while Freedom restarts the node ([#988](https://github.com/solardev-xyz/freedom-browser/issues/988)). Retry with backoff. - `node-not-ready`: the node is still connecting, or a storage batch bought moments ago is not yet known to the network. Retry later. - `ultra-light-mode`, `no-usable-stamps`: the node cannot publish yet (no Gnosis Chain connection, or no storage with room for the write). On a write method, all four of these also open Freedom's publish setup for the user, so tell them what is happening rather than retrying in a loop. Reads only ever report `node-stopped`. A `4900` without `data` means the provider is disabled (**Settings → Advanced → Enable Identity & Wallet** is off) or the app's permission manifest could not be fetched. Check `getCapabilities()` up front: `canPublish` is false until the origin is connected and the node is ready. **The request is wrong (`-32602`).** Fix the call. `data.reason` names the problem, sometimes with `data.limit` and `data.actual`. Two are retryable: `rate_limited` (wait for the 60 s read window, or `retryAfterMs` for new GSOC topics) and `too_many_subscriptions` (close one first). `-32603` is an internal error or a timeout and is usually transient. A request that timed out may still have completed on the node, and a response that arrives after the page navigated away is never delivered. ## Timeouts `window.swarm` gives publish, feed, signing and messaging calls 300 s and everything else 60 s, prompt time included. A user who takes longer than 60 s on the connect prompt gets `-32603 Request timed out` even though the grant still lands; call `requestAccess` again to pick it up. `window.radicle` uses 300 s for seeding and writes and 60 s otherwise. `radicle_unseed` currently gets only 60 s ([#1001](https://github.com/solardev-xyz/freedom-browser/issues/1001)). ## Radicle specifics `window.radicle` uses the same codes. Its `4900` reasons are `profile-disabled` (Radicle is off for this profile) and `node-stopped`; the node-status, access and disconnect methods still work while the node is stopped. Write validation failures are `-32602` with reasons such as `invalid_rid`, `invalid_title` or `payload_too_large`. The full list is in [Errors](radicle.html.md#errors). Full tables: [`window.swarm` errors](swarm.html.md#errors).