Errors and fallbacks

Every evaluation has two fallback layers: the environment fallback and the caller default. They solve different problems and should be chosen deliberately.

The environment fallback is normal configuration when no targeting group matches. The caller default is application policy when FeatureGate cannot resolve a valid typed value.

When the caller default is used

The caller default applies when a flag is:

• Missing from the project.
• Archived or inactive.
• Unconfigured in the key-bound environment.
• Hidden from a browser client.
• Read with a mismatched getter or default type.
• Unavailable because a hosted request failed.

Missing targeting context is different. A condition misses, evaluation continues to later groups, and the configured environment fallback wins if no group matches.

An active kill switch is also not an error. Its emergency value wins before rules and fallback.

Choose safe defaults

Choose a default for the failure mode, not merely the most common value. Ask what the application should do when configuration is missing, the network is unavailable, or a deployment contains an old key.

For a release, the existing behaviour is often safest. For an operational control, the safe state depends on whether failure should preserve service or stop risky work.

Do not use a default to hide integration failure indefinitely. Details getters and application monitoring should reveal sustained use of defaults during startup or hosted failure.

Node.js initialization failures

initialize() rejects when the first remote snapshot cannot be loaded or validated. Decide whether the process should:

1. Fail startup and let the platform restart it.
2. Retry within a bounded startup window.
3. Continue with reviewed bootstrap flags.
4. Continue with caller defaults in a documented degraded mode.

Do not catch and ignore initialization errors without selecting one of these policies.

Refresh failures

Explicit refresh() rejects with a typed error. Automatic polling reports failures through onError. After a successful load, both leave the last valid snapshot available.

Monitor the age of the last successful refresh. A client that continues evaluating is not necessarily current. Repeated authentication errors usually require key rotation rather than retry.

SDK error	Meaning	Response
FeatureGateAuthenticationError	Key rejected with 401 or 403	Inspect key, scope, and organisation state
FeatureGateConfigurationError	Options or snapshot are invalid	Correct configuration before retry
FeatureGateRequestError	Timeout, rate limit, network, or 5xx	Preserve safe state and retry only when bounded

HTTP failures

Status	Action
400	Correct request shape, duplicate keys, context, or types
401	Replace a missing, malformed, unknown, or revoked key
403	Check family, scope, origin, exposure, binding, and lifecycle
413	Reduce body, batch, or context size
429	Respect retry information and reduce pressure
5xx	Use defaults and retry with bounded backoff if latency permits

WORKSPACE_OFFBOARDING is the stable compatibility code for an organisation in its export window or deletion-pending state. Credential rotation does not bypass organisation lifecycle enforcement.

Diagnose an unexpected default

1. Confirm the flag key and expected type.
2. Confirm the credential belongs to the intended project environment.
3. Confirm the flag is active and configured there.
4. For browser calls, confirm exposure and exact allowed origin.
5. Inspect evaluation details or response reason.
6. Test the same context with required paths present and absent.
7. For snapshots, inspect last successful refresh and version.

Safe diagnostics

Record request ID, time, route, status, key prefix, project, environment, and error class. Never log raw keys, authorization headers, cookies, full context, request bodies, targeting values, or resolved values.

Related pages: Troubleshooting and limits, Snapshots and freshness, and Evaluation credentials.