splitchFailure behavior.
Server evaluation never throws on a platform failure and never hides one. Empty or non-string explicit idempotency keys throw, as does UUID generation when the runtime cannot provide it. Peek throws, and so does a browser read before init().
A failure is always observable and never a silently disguised default. That is the whole contract; the shape it takes depends on the method.
evaluate, evaluateDetails, verify
On the server client these never throw on a platform failure and never retry. On any such failure (HTTP error, timeout, network error, unparseable body) they return your defaultValue (or false when you gave none), log loudly through logger.error, and report reason: "ERROR" plus an errorCode in ResolutionDetails. For evaluate and evaluateDetails, an empty or non-string explicit idempotencyKey throws SDK_CONTEXT_INVALID. If the key is omitted and crypto.randomUUID is unavailable, the call throws SDK_IDEMPOTENCY_KEY_UNAVAILABLE.
The default value is returned so your request path keeps serving, and the loud log plus the ERROR reason are what stop that from becoming a silent outage. If you only read the value, you cannot tell a resolved false from a fallback false: read reason when the difference matters.
The browser client has one throw
The browser client resolves from a payload it fetched in init(), so there is nothing to fall back to until that payload exists. evaluate, evaluateDetails, and the useFlag / useFlagDetails hooks throw SDK_NOT_INITIALIZED when they are read before init() resolves, and init() itself throws on a failed fetch. Once it has resolved, reads follow the rule above and never throw: a revalidation failure marks the payload degraded rather than clearing it.
In React that throw surfaces during render, so await init() before mounting SplitchProvider, or render the tree behind an error boundary.
peekVariant
Throws a SplitchSdkError carrying code, status, and docsUrl. Peek is an inspection call with no user path to keep serving, so failing loudly is the correct behavior rather than returning something plausible.
Reading the error
Every SplitchSdkError message is one line in a fixed shape, and every code resolves to a page:
UNAUTHORIZED: Cause: <what happened>. Remediation: <what to do>. Docs: https://splitch.dev/docs/error/UNAUTHORIZEDThe full catalog is at /docs/errors, and the machine-readable index is at /llms.txt.