Skip to main content

API Error Codes

Reference guide for Toggly API error codes and how to resolve them.

HTTP Status Codes​

401 Unauthorized​

Meaning: Authentication failed or token is invalid.

Common Causes:

  • Invalid or missing Bearer token
  • Expired token
  • Token was invalidated (logged out)
  • Using API key instead of Bearer token

Solutions:

# Verify your token works
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.toggly.io/api/v2/applications

# If it fails, sign in again to get a new token

When this happens:

  • API requests (not SDK usage)
  • Browser extension requests
  • CLI operations

SDK Impact: SDKs use app keys, not bearer tokens, so this typically doesn't affect SDK operations.

403 Forbidden​

Meaning: You don't have permission to access this resource.

Common Causes:

  • Insufficient permissions for the requested action
  • Not a member of the team/workspace
  • Resource belongs to different organization
  • Plan limitation (feature not included in your tier)

Solutions:

  1. Check Team Membership:

    • Go to Settings → Teams
    • Verify you're a member
    • Check your role (Viewer, Member, Admin)

  2. Verify Resource Ownership:

    • Confirm you're in the correct workspace
    • Check if the resource exists
    • Verify you have permissions

  3. Plan Limitations:

    • Some features require paid plans
    • Check if feature is included in your subscription
    • Upgrade your plan if needed

404 Not Found​

Meaning: The requested resource doesn't exist.

Common Causes:

  • Feature flag doesn't exist
  • Wrong environment
  • Typo in feature key
  • Resource was deleted

Solutions:

// Verify the feature key is correct
const featureKey = 'my-feature'; // Check spelling

// Verify it exists in the dashboard
console.log('Looking for feature:', featureKey);

// Check if it exists in this environment
const exists = await toggly.featureExists(featureKey);

429 Too Many Requests​

Meaning: You've exceeded the rate limit.

Common Causes:

  • Making too many API requests
  • Not caching definitions locally
  • Calling API in a tight loop
  • DDoS or abuse detection triggered

Solutions:

  1. Implement Caching:
// Cache definitions locally
const toggly = new TogglyClient({
  appKey: 'your-key',
  environment: 'production',
  cacheTimeout: 300000, // Cache for 5 minutes
});
  1. Batch Operations:
// ❌ Bad - multiple individual calls
const flag1 = await toggly.isEnabled('feature-1');
const flag2 = await toggly.isEnabled('feature-2');
const flag3 = await toggly.isEnabled('feature-3');

// ✅ Good - evaluate multiple flags at once
const results = await toggly.evaluateAll(['feature-1', 'feature-2', 'feature-3']);
  1. Check Rate Limits:

Rate Limits by Plan:

  • Free: 100 requests/minute
  • Paid: 1,000 requests/minute
  • Enterprise: Custom limits

500 Internal Server Error​

Meaning: Server encountered an error processing your request.

Common Causes:

  • Temporary server issue
  • Malformed request payload
  • Server bug

Solutions:

  1. Retry with exponential backoff:
async function retryRequest(fn: () => Promise<any>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 500 && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)));
        continue;
      }
      throw error;
    }
  }
}

  1. Check Status Page:

  2. Contact Support:

    • If error persists, email [email protected]
    • Include request ID from error response
    • Provide timestamp and steps to reproduce

503 Service Unavailable​

Meaning: Service is temporarily unavailable.

Common Causes:

  • Scheduled maintenance
  • Service deployment
  • High load (rare)

Solutions:

  1. Check Status Page - status.toggly.io
  2. Wait and Retry - Usually resolves in 1-5 minutes
  3. Use Cached Values - SDKs should fall back to cached definitions
  4. Implement Fallback:
try {
  await toggly.init();
} catch (error) {
  if (error.status === 503) {
    // Use default values or cached data
    console.warn('Toggly unavailable, using defaults');
  }
}

SDK-Specific Error Handling​

Different SDKs handle errors differently:

  • JavaScript - Promise rejections
  • .NET - Try-catch with specific exceptions
  • PHP - Exception handling
  • Go - Error return values

General Error Handling Best Practices​

1. Always Handle Errors​

try {
  await toggly.init();
} catch (error) {
  console.error('Toggly initialization failed:', error);
  // Use default flag values
}

2. Log Error Details​

catch (error) {
  console.error('Error details:', {
    status: error.status,
    message: error.message,
    requestId: error.requestId, // If available
    timestamp: new Date().toISOString()
  });
}

3. Implement Fallbacks​

const toggly = new TogglyClient({
  appKey: 'your-key',
  environment: 'production',
  defaults: {
    'new-feature': false,  // Fallback if API fails
    'beta-feature': false,
  }
});

Getting Help​

If authentication issues persist:

  1. Verify credentials in dashboard
  2. Check Common Issues guide
  3. Enable debug logging in your SDK
  4. Ask on GitHub Discussions
  5. Contact support at [email protected]