Troubleshooting

Common issues and their solutions.

Enable Debug Mode First

Before troubleshooting, enable debug mode to see detailed console logs:

FitSignal.init({
  apiKey: 'fs_live_your_api_key',
  debug: true  // Enable debug logging
});

This will log all SDK operations to the browser console, helping you identify issues quickly.

"Invalid API key" Error

Error Message

FitSignal: Invalid API key format

Causes and Solutions

Check the API key format

API keys must start with fs_live_ or fs_test_.

Verify the key is not truncated

Make sure you copied the full API key from the dashboard.

Check for typos

Ensure there are no extra spaces or characters in the key.

Widget Not Showing

1. User not identified

The SDK requires a user to be identified before showing surveys. Make sure you call identify():

// This must be called for the widget to show
await FitSignal.identify({
  email: 'user@example.com'
});

2. User not eligible

The user may have already completed the survey or doesn't match the targeting criteria. Check eligibility:

const eligible = await FitSignal.isEligible();
console.log('User eligible:', eligible);

3. Widget disabled in settings

Check that the widget is enabled for this survey in the dashboard under Survey Settings → Widget Settings.

4. Trigger type set to manual

If the trigger type is "manual", the widget won't auto-show. You need to call FitSignal.show() explicitly.

5. Cooldown period active

If the user dismissed the survey recently, they may be in a cooldown period. Check the cooldown settings in your survey configuration.

6. Page targeting rules

Check if page targeting rules are set. The widget only shows on pages that match the "Show on pages" patterns and don't match "Hide on pages" patterns.

CORS Errors

Error Message

Access to fetch at 'https://www.fitsignal.com/api/widget/...' has been blocked by CORS policy

Causes and Solutions

Verify your domain is allowed

Your domain must be added to the allowed origins in your FitSignal project settings. Go to Dashboard → Settings → API Keys and add your domain.

Check for localhost

During development, make sure http://localhost:3000 (or your local port) is added to allowed origins.

Check the protocol

Make sure to include the correct protocol (http:// or https://) when adding domains.

Rate Limiting (429 Errors)

Error Message

HTTP 429: Too Many Requests

FitSignal has rate limits to prevent abuse. The widget SDK is designed to work within these limits under normal usage.

Common causes

Calling identify() too frequently

Only call identify() once per session or when user data changes. Don't call it on every page load.

Multiple SDK instances

Make sure you're not initializing the SDK multiple times (e.g., in a component that renders frequently).

Rate Limits

Endpoint	Limit
identify	60 requests/minute per IP
survey	120 requests/minute per IP
submit	30 requests/minute per IP

Survey Already Responded

If a user has already completed a survey, they won't see it again. This is by design to prevent survey fatigue.

For testing

To test the survey flow again during development:

// Clear the SDK state (useful for testing)
FitSignal.reset();

// Then identify again
await FitSignal.identify({
  email: 'user@example.com'
});

Note

reset() clears local state, but the server still records the response. The user will still be marked as having completed the survey on the backend.

Widget Styling Issues

Widget appears behind other elements

Increase the z-index in your init options:

FitSignal.init({
  apiKey: 'fs_live_your_api_key',
  zIndex: 99999  // Higher than other elements
});

Widget position conflicts with your UI

Change the widget position:

FitSignal.init({
  apiKey: 'fs_live_your_api_key',
  position: 'bottom-left'  // or 'center'
});

Still need help?

If you're still experiencing issues after trying these solutions:

Email us at support@fitsignal.com
Include your API key prefix (e.g., fs_live_abc...) and debug console logs
Describe the expected vs actual behavior