docs

SDK reference

@lymit/sdk options, methods and failure semantics.

`new Lymit(options)`

Option	Default	Notes
`apiKey`	—	Required. `lym_live_…`
`baseUrl`	`https://api.lymit.io`	Point at staging or a local edge
`failMode`	`"open"`	`"open"` allows the request and calls `onError` when Lymit is unreachable or errors; `"closed"` rejects it
`timeoutMs`	`3000`	Per attempt; a timeout counts as a transport failure
`onError`	`console.warn`	Receives a `LymitError` whenever `failMode` kicks in
`enableEphemeralCache`	`true`	Remember rejected identifiers in-process until their `reset`, so repeat offenders cost no network call
`fetch`	global `fetch`	Inject for tests or custom agents

`lymit.namespace(name, config)`

Validates config immediately (a typo fails at startup) and returns a Namespace with limit().

`namespace.limit(identifier, { cost? })`

Resolves to a LimitResponse. Validation of identifier and cost happens before any network call.

Failure semantics

Rate-limit rejection → success: false. Never throws.
Transport failure or timeout → one retry, then failMode applies.
Server error (5xx) → no retry; failMode applies.
Client error (invalid_api_key, feature_not_in_plan, bad_request, quota_exceeded, too_many_requests) → always throws a LymitError with code and status, regardless of failMode. These are things to fix, not outages to ride through.

With the default failMode: "open", a Lymit outage can never take your application down: the request is allowed with remaining = limit and you are told through onError.

Runtimes

The package ships ESM and CommonJS builds and is tested on every release against Node (both module systems), Bun, Deno and Cloudflare Workers (workerd). It uses only fetch, AbortController and setTimeout.