# Errors and fallbacks

Handle startup, refresh, authentication, missing flags, and stale configuration safely.

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](/docs/operate/troubleshooting-and-limits),
[Snapshots and freshness](/docs/evaluate/snapshots-and-freshness), and
[Evaluation credentials](/docs/evaluate/credentials).