# Troubleshooting and limits Diagnose credentials, configuration, targeting, freshness, payloads, and organisation state. Start with the symptom, then identify the boundary that owns it. Capture request ID, time, route, status, key prefix, project, and environment before changing configuration. Never include raw keys, authorization headers, cookies, full context, request bodies, targeting values, or resolved values in logs or support material. ## `401` authentication failure Likely causes: - Missing or malformed `Authorization: Bearer` header. - Unknown key or incorrect credential family. - Revoked key. - Lost or truncated secret. Confirm the safe key prefix and intended caller. Create a replacement when the raw one-time secret is lost; it cannot be recovered from the console or activity. Do not retry an unchanged `401`. Correct or rotate the credential first. ## `403` authorization or lifecycle failure Inspect the response error code. Confirm: - Runtime, client, or management key family. - Required endpoint scope. - Project and environment binding. - Exact browser origin. - Client exposure for each browser flag. - Environment active state. - Owning organisation lifecycle. `WORKSPACE_OFFBOARDING` is the compatibility code for an organisation in its export window or deletion-pending state. Rotating keys cannot bypass it. ## The caller receives its default Check in this order: 1. Exact flag key. 2. Expected getter or request type. 3. Credential project and environment. 4. Flag active state. 5. Environment configuration presence. 6. Browser exposure and allowed origin. 7. Evaluation details or hosted response reason. A configured fallback of `false` is not the same as using the caller default. Use details to identify which layer produced the value. ## A targeting rule does not match Confirm the rule order, group mode, attribute path, value type, and normalization. Test the context with required paths present and absent. Missing attributes are misses, including for `not equals` and `not in`. A broad earlier group can make later exceptions unreachable. For percentage rules, confirm the rollout attribute is stable and identical across services. Changing the path or identifier format can reshuffle subjects. ## A value is stale Node.js clients poll every 30 seconds by default. Wait for the next successful poll or call `refresh()` once when immediate verification is justified. Inspect the last successful refresh, snapshot version, and polling errors. A failed background refresh preserves the last valid snapshot. Confirm one intended singleton configuration is running. Old bootstrap data or multiple clients with different keys can make processes disagree. ## Browser request is rejected Confirm the key is a publishable client key with `client:evaluate`. The request must include an exact allowed `Origin`. Check scheme, hostname, and port. `http://localhost:5173` and `http://localhost:3000` differ. Ensure the flag is client-exposed in the key-bound environment. Never replace the client key with a server key to make CORS work. ## `400` invalid request Use the validation error to inspect: - Missing `flags` or `evaluations`. - Supplying both request forms. - Empty or duplicate keys. - Invalid typed defaults. - Excess context fields or depth. - Malformed JSON. Correct the caller. Repeating the same request will not succeed. ## `413` payload too large Reduce the evaluation batch or context. Send only attributes used by active rules. Do not split one operation into per-flag loops unless batching within the current limit is impossible. The generated endpoint reference and validation response are authoritative for current code-owned limits. ## `429` rate limited Respect retry information. Batch related flags, reuse snapshots where appropriate, and remove per-flag HTTP loops. Do not create many runtime keys to evade policy. Rate limits protect the service at key, organisation, and plan boundaries. ## `5xx`, timeout, or network failure Apply safe caller defaults or retain the last valid snapshot. Retry with bounded backoff only when the operation latency budget permits it. Monitor duration and frequency. A fallback that keeps the application available can still hide a sustained integration outage if nobody observes it. ## Environment is not ready Follow the lifecycle sequence: active environment, active flag, configuration, runtime key, first hosted request, then default review. A local SDK getter does not prove hosted activation. Use a hosted request to validate key binding and API reachability. ## Management automation fails Confirm the key is a management key with the required organisation and project scopes. Runtime keys cannot call management routes. Management remains preview and supports only the shipped discovery, flag, configuration, runtime-key, and project-audit workflows. Targeting and tags are not currently automated. ## Escalate safely Provide: - UTC or local time with timezone. - Request ID. - Route and HTTP status. - Safe key prefix and credential family. - Organisation, project, and environment identity. - SDK version and error class when relevant. - Last successful snapshot refresh time. Do not provide the raw credential, request body, context, cookies, user agent, IP address, or resolved flag value unless a separate secure support process explicitly requires narrowly scoped data. Related pages: [Errors and fallbacks](/docs/evaluate/errors-and-fallbacks), [Environment readiness](/docs/operate/environment-readiness), and the [API reference](/docs/api/reference/getting-started).