Problem
A consistent stream of support tickets come in for API and SDK errors that customers could diagnose themselves if there was a troubleshooting reference. These tickets often follow the same pattern: customer sees an error, doesn't know what it means, opens a ticket, and a support engineer explains it in 2 minutes. Some of these escalate to engineering unnecessarily.
Common recurring questions:
- "I'm getting 502 errors from the Flagsmith API"
- "My API key returns 403"
- "SDK initialization times out"
- "Flag values aren't updating after I change them"
- "I'm getting rate limited but don't know what the limits are"
What's missing
A troubleshooting page covering the most common error scenarios, organized by symptom:
HTTP errors
- 401/403: Server-side key vs client-side environment key. Using the wrong key type for the endpoint. Key scope (project vs environment).
- 404: Wrong API base URL, incorrect environment key, endpoint path errors.
- 429: Rate limits - what they are per plan, how to check current usage, how to reduce call volume (local evaluation, caching).
- 502/503: Typically transient. When to retry vs. when to check status page. Self-hosted: common causes (database connection pool, task processor backlog).
- 504/Timeout: Large environment documents, too many features/segments. How to diagnose with request timing.
SDK issues
- Flags not updating: Caching behavior per SDK, polling intervals, real-time/SSE configuration.
- Default values returned: SDK not initialized, environment key wrong, network issues.
- Identity/trait evaluation unexpected: Trait type mismatches (string "true" vs boolean true), evaluation order.
Self-hosted specific
- Task processor errors: What it does, common failure modes, how to check logs.
- Database migration failures: Version compatibility, how to check migration status.
Suggestion
Create a dedicated troubleshooting page at something like docs.flagsmith.com/guides/troubleshooting and link it prominently from:
- The support page (docs.flagsmith.com/support/)
- The API reference
- Each SDK's getting started page
Structure it as symptom-first ("I'm seeing X") rather than component-first ("The API returns...") since customers think in terms of what they observe, not which system is responsible.
Why this matters
These are the most deflectable tickets in the support queue. A customer hitting a 403 doesn't need a human - they need a page that says "403 usually means you're using a server-side key on a client-side endpoint, here's how to check." Each fix documented here is a permanent reduction in support load and engineering escalations.
Problem
A consistent stream of support tickets come in for API and SDK errors that customers could diagnose themselves if there was a troubleshooting reference. These tickets often follow the same pattern: customer sees an error, doesn't know what it means, opens a ticket, and a support engineer explains it in 2 minutes. Some of these escalate to engineering unnecessarily.
Common recurring questions:
What's missing
A troubleshooting page covering the most common error scenarios, organized by symptom:
HTTP errors
SDK issues
Self-hosted specific
Suggestion
Create a dedicated troubleshooting page at something like
docs.flagsmith.com/guides/troubleshootingand link it prominently from:Structure it as symptom-first ("I'm seeing X") rather than component-first ("The API returns...") since customers think in terms of what they observe, not which system is responsible.
Why this matters
These are the most deflectable tickets in the support queue. A customer hitting a 403 doesn't need a human - they need a page that says "403 usually means you're using a server-side key on a client-side endpoint, here's how to check." Each fix documented here is a permanent reduction in support load and engineering escalations.