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 failureLikely causes:
Authorization: Bearer header.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 failureInspect the response error code. Confirm:
WORKSPACE_OFFBOARDING is the compatibility code for an organisation in its export window or
deletion-pending state. Rotating keys cannot bypass it.
Check in this order:
A configured fallback of false is not the same as using the caller default. Use details to identify
which layer produced the value.
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.
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.
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 requestUse the validation error to inspect:
flags or evaluations.Correct the caller. Repeating the same request will not succeed.
413 payload too largeReduce 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 limitedRespect 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 failureApply 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.
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.
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.
Provide:
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, Environment readiness, and the API reference.