Troubleshooting

HTTP errors

401 Unauthorized

Cause: Missing, invalid, or revoked API key.

Fix:

1. Verify Authorization: Bearer ft_... header is set.
2. Copy a new key from Environment → API keys → Create key (old full value cannot be recovered).
3. Check the key status is still Active (not Revoked).

SDK behavior: Clears cache and stops SSE stream. Call init() again after fixing the key.

403 Forbidden

Cause: API key scope violation.

Fix:

The SDK logs a one-time console.warn with the API error message.

404 Feature not found

Cause: On GET /v1/features/:key only, for an unknown key or a disabled feature.

Fix:

1. Check the key spelling (case-sensitive).
2. Enable the feature on Feature definitions (row menu → Enable), or set an override on Environment → Overrides.
3. Use GET /v1/features bulk fetch. Disabled features are silently omitted, not errored.

SDK: Missing keys return isEnabled() === false and getValue() === undefined.

400 Bad Request

Cause: Invalid type or deprecated query param on GET /v1/features.

Fix: Use only boolean, string, number, json for type; true or false for deprecated.

304 Not Modified

Not an error. Features unchanged since the last ETag. SDK keeps existing cache.

429 Too Many Requests

Cause: Account usage limit exceeded for the current period.

Fix: Wait for the next period or contact support. Reduce unnecessary refresh() calls; unchanged data returns 304 automatically.

SDK issues

Features not updating after dashboard toggle

Typical latency: seconds with SSE; up to poll interval (default 30s) with stream: "off"; up to ~60s worst case without stream or poll.

init() throws on first load

Cause: Network failure or invalid key on first fetch.

Fix: Verify API key, network, and origin scope (test key on localhost). Check browser console for error details.

Stale values on server

Cause: Shared FeatureToggleServer without refresh().

Fix: await ft.refresh() before reads, or use per-request instances.

Deprecated warning in console

Expected. One-time warning per deprecated key. Migrate to inFavorOf replacement when set.

Stream keeps reconnecting

Cause: Network interruption, proxy timeout, or close() called.

Fix: SDK uses exponential backoff automatically. Check corporate proxies allow long-lived SSE to api.featuretoggle.com.

Dashboard issues

Cannot add staging/production

Cause: The account may not have deploy access yet.

Fix: On the free plan, click Add staging or Add production and choose Upgrade plan, or open Billing in the sidebar. Contact support if you already have a paid plan and still cannot add environments.

Cannot delete development environment

By design. development is permanent and seeded on project create.

Feature key cannot be edited

By design. Keys are immutable after create. Create a new feature on Feature definitions, then Deprecate the old one (optionally choose a Replacement feature).

Type cannot be changed

Cause: Active API keys or environment overrides exist.

Fix: Revoke API keys and choose Use default on overrides, or create a new feature with the correct type.

Direct API debugging

# Bulk fetch
curl -sD - https://api.featuretoggle.com/v1/features \
  -H "Authorization: Bearer YOUR_KEY"

# Conditional fetch
curl -sD - https://api.featuretoggle.com/v1/features \
  -H "Authorization: Bearer YOUR_KEY" \
  -H 'If-None-Match: "1"'

# Single feature
curl -s https://api.featuretoggle.com/v1/features/my-feature \
  -H "Authorization: Bearer YOUR_KEY"

# SSE stream
curl -N https://api.featuretoggle.com/v1/features/stream \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Accept: text/event-stream"

Look for ETag and status code in response headers.

Still stuck?

1. Confirm environment matches the key prefix (ft_test_ → development, ft_live_ → staging or production).
2. Review Security for key placement.
3. Review Caching and syncs for expected refresh behavior.