Gate Troubleshooting

Common Gate issues with diagnosis steps and resolutions.

Flag changes not taking effect

Diagnosis: Fetch the flag directly to confirm the API has the new value.

curl https://api.solenoid.systems/v1/gate/{flag_key} \
  -H "Authorization: Bearer $API_KEY"

Resolution:

  • Application cache: Clear or refresh your local flag cache.
  • Propagation delay: Flag updates propagate globally within 60 seconds. Wait and re-check.
  • SDK refresh: Ensure your client is polling GET /v1/gate/config every 30-60 seconds.
  • CDN/proxy cache: Add Cache-Control: no-cache to bypass intermediate caches.

Config endpoint returning stale data

Diagnosis: Compare the config endpoint with the single-flag endpoint. If they differ, a cache layer is returning old data.

curl https://api.solenoid.systems/v1/gate/config \
  -H "Authorization: Bearer $API_KEY"

curl https://api.solenoid.systems/v1/gate/{flag_key} \
  -H "Authorization: Bearer $API_KEY"

Resolution:

  • Add Cache-Control: no-cache to your request headers.
  • Check your HTTP client (axios, fetch) for built-in response caching.
  • Wait 60 seconds after updating a flag for global propagation.

Flag always returns default / feature_not_found

Diagnosis: List all flags to confirm the flag exists.

curl https://api.solenoid.systems/v1/gate \
  -H "Authorization: Bearer $API_KEY"

Resolution:

  • Flag does not exist: Create it with POST /v1/gate.
  • Key is misspelled: Flag keys are case-sensitive. Copy the exact key from the list response.
  • Wrong API key: Each API key has its own flag namespace. Verify you are using the correct key.
  • Prevention: Store flag keys as constants in your codebase and validate flag existence at startup.

Intermittent evaluation failures (500)

Diagnosis: Check whether the issue is transient or persistent. Retry the request.

curl https://api.solenoid.systems/v1/gate/config \
  -H "Authorization: Bearer $API_KEY" \
  --max-time 10

Resolution:

  • Retry with backoff. Transient failures usually resolve on the next request.
  • Fall back to cached config. Serve the last-known-good flag state on failure.
  • Check rate limits. Look for 429 responses in your logs. See Rate Limits.
  • Contact support if 500 errors persist, with the flag key and timestamp.

High latency on flag checks

Diagnosis: Measure the round-trip time to the config endpoint.

time curl https://api.solenoid.systems/v1/gate/config \
  -H "Authorization: Bearer $API_KEY"

Resolution:

  • Use the bulk config endpoint. One GET /v1/gate/config request replaces multiple individual flag checks.
  • Cache locally. Store config in memory or localStorage. Refresh in the background.
  • Do not block rendering on flag evaluation. Render with defaults, then update when flags arrive.