Error Handling

Errors thrown at construction time

These happen synchronously in the Keyset constructor — wrap in try/catch or fix the config.

TypeScriptCopy
try {
  const client = new Keyset({ apiKey: "", cacheTTL: 0 });
} catch (err) {
  console.error(err.message); // "API key is required"
}

---

Errors thrown at runtime (async)

Wrong key mode

Calling a write method (create, update, delete, dashboardList) with a public key (pkey_…) throws synchronously before any network call:

TypeScriptCopy
// Client created with a public key
const client = new Keyset({ apiKey: "pkey_abc", cacheTTL: 0 });

try {
  await client.content.create({ key: "x", value: 1, type: "number" });
} catch (err) {
  console.error(err.message); // "This operation requires a secret key"
}

Network / HTTP errors

The HttpClient throws an Error when:

• The server responds with a non-2xx status — message is taken from response.data.error if present, otherwise "Request failed"
• The request exceeds timeout — the browser's AbortController fires and throws an AbortError

TypeScriptCopy
try {
  const data = await client.content.getAll();
} catch (err) {
  if (err.name === "AbortError") {
    console.error("Request timed out");
  } else {
    console.error("Request failed:", err.message);
  }
}

---

Retry behaviour

When retries > 0, the SDK re-attempts failed requests up to that many times before throwing. Between retries it waits using exponential backoff:

delay = 2^attempt × 100 ms

TypeScriptCopy
const client = new Keyset({
  apiKey: "pkey_abc",
  cacheTTL: 0,
  retries: 3,   // retry up to 3 times
  timeout: 8000,
});

The error is only thrown after all retry attempts are exhausted.

---

Error handling in React hooks

useContent catches errors internally and surfaces them in the error state field — it never throws in render. Always check error before using data:

TypeScript JSXCopy
const { data, loading, error } = useContent();

if (loading) return <Spinner />;
if (error)   return <ErrorBanner message={error} />;

return <Dashboard data={data} />;

The typed hooks (useKeysetString, useKeysetBoolean, etc.) silently return defaultValue when a key is missing or has the wrong type. They do not expose an error field — if you need error visibility, use useContent or useContentKey instead.

---

Best practices

• Use public keys client-side — a public key can only read, so leaking it is less severe than leaking a secret key.
• Never expose secret keys in front-end code — environment variables accessed in browser bundles (e.g. VITE_*, NEXT_PUBLIC_*) are visible to anyone. Secret keys must only live in server-side code.
• Set a timeout — the default is 5 000 ms. Tune it based on your SLA requirements.
• Enable retries for critical config — for config that must be loaded at startup, setting retries: 2 or retries: 3 provides resilience against transient network failures.
• Use defaultValue — always pass a sensible default to the typed getters so your app degrades gracefully if a key hasn't been created yet in Keyset.