Troubleshooting

The real failures we see, and the exact fix for each.

Every entry maps a symptom to a concrete fix. If you hit something not on this list, capture the request/response and open an issue.

Auth & keys

Common mistakes

If you get 401 Unauthorized — the Authorization header is missing or the key was revoked. Re-copy from Apps → API keys.
If you get 403 Forbidden — the key belongs to a different app or a different environment. Test keys can't touch Production data.
If you enabled request signing on a mobile app — disable it — the signing secret is not safe in a client binary. See Authentication.

Common mistakes

If you get 404 Not Found — either the URL path is wrong (paths are exactly /api/public/sdk/v1/<name> — no trailing slash) OR the target app / device / form / post could not be found for this key. Check both.
If you get 400 with a validation message — read the JSON body — it names the field that failed.
If you get 413 — your body exceeded the endpoint's cap (16 KiB for /sync, 32 KiB for /register, 64 KiB for /controls/events, 256 KiB for /events). Batch fewer items.
If you get 429 — read Retry-After and back off. See rate limits.

Common mistakes

If flag value does not update on the device — you edited a rule instead of the Default treatment, or the SDK poll interval hasn't fired. Force a refresh.
If a killed app stays live on some devices — those devices haven't reached /session — the block only applies on the next launch or resume. See block rules.
If a control returns default values only — the server considers the device ineligible — check targeting and app_version.

Common mistakes

If browser fetch is blocked by CORS — hitting the correct https://ctrlapp.krdcode.com host — CORS is enabled there. A private origin will not work.
If the SDK errors before any request — a required option (apiKey, deviceId) is missing or empty.
If installing an SDK fails with “package not found” — the registry release is still pending — see SDK & package availability.