SDK reliability model

How local evaluation, conditional synchronization, stale cache, and fallbacks work together.

Server-side essentials
Security and runtime requirements for every integration.

Official SDKs are server-side only.

Never expose API keys in browser or client code.

Store API keys in environment variables.

The default fallback is false.

SDKs fail safely if SwitchPilot is unreachable.

Default cache TTL: 60 seconds.

Default stale-if-error window: 5 minutes.

evaluation flow
periodic or manual refresh
→ local cache of all flags
→ local evaluations
→ ETag revalidation
→ Last Known Good on temporary failure
→ fallback only when no usable configuration exists

Default windows

Default cache TTL: 60 seconds.

Default stale-if-error window: 5 minutes.

Local evaluation

isEnabled() and is_enabled() read the local in-memory cache. When synchronization is required, concurrent callers share a single refresh. refresh() performs an explicit network synchronization. No evaluation telemetry is collected.

ETag and 304

A successful 200 response replaces the cache and stores its ETag. The next refresh sends If-None-Match. A 304 has no body: the SDK retains the existing values and renews the cache freshness timestamp.

Last Known Good

Invalid JSON or flags never replace a valid cache. After a timeout, network error, server error, or 429, the SDK can use stale values untillast success + TTL + stale-if-error. The default stale-if-error duration is five minutes and is never extended by failed attempts.

Fallback and missing keys

With a usable cache, a missing key uses its per-call fallback and then the client fallback. When no usable configuration exists, evaluation uses the fallback directly. The fallback is a local SDK decision, not a value returned by SwitchPilot.

Rate limiting and status

A 429 response records Retry-After and causes no retry loop. Until the deadline, the client uses a usable cache or fallback without another request. getStatus() and get_status() expose freshness, stale use, safe errors, ETag, and rate-limit state without network access or API-key disclosure.

  • whether a cache is present and currently fresh;
  • whether a stale Last Known Good configuration is in use;
  • the last successful synchronization and last attempt;
  • the last safe error code/message and current ETag;
  • the rate-limit deadline, when one is active.