Best Practices

async function stravaRequest(endpoint, accessToken) {
  const response = await fetch(`https://www.strava.com/api/v3${endpoint}`, {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });

  // Check rate limits (read limits are usually the ones you hit first)
  const limitHeader = response.headers.get('X-RateLimit-Limit');
  const usageHeader = response.headers.get('X-RateLimit-Usage');
  const readLimitHeader = response.headers.get('X-ReadRateLimit-Limit');
  const readUsageHeader = response.headers.get('X-ReadRateLimit-Usage');

  if (limitHeader && usageHeader) {
    const [limit15min, limitDaily] = limitHeader.split(',').map(Number);
    const [usage15min, usageDaily] = usageHeader.split(',').map(Number);

    console.log(`15min: ${usage15min}/${limit15min}, Daily: ${usageDaily}/${limitDaily}`);
  }

  if (readLimitHeader && readUsageHeader) {
    const [readLimit15min] = readLimitHeader.split(',').map(Number);
    const [readUsage15min] = readUsageHeader.split(',').map(Number);

    // Warn if approaching the read limit
    if (readUsage15min > readLimit15min * 0.8) {
      console.warn('Approaching 15-minute read rate limit');
    }
  }

  // Handle 429 Too Many Requests
  if (response.status === 429) {
    // Strava doesn't document a Retry-After header; wait for the next 15-minute window
    console.error('Rate limited. Retry after the 15-minute window resets');
    throw new Error('Rate limited');
  }

  return response.json();
}

class StravaAPIError extends Error {
  constructor(status, message, response) {
    super(message);
    this.status = status;
    this.response = response;
  }
}

async function stravaFetch(endpoint, accessToken, options = {}) {
  const response = await fetch(`https://www.strava.com/api/v3${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      ...options.headers
    }
  });

  if (!response.ok) {
    const errorBody = await response.text();

    switch (response.status) {
      case 401:
        throw new StravaAPIError(401, 'Token expired or invalid', errorBody);
      case 403:
        throw new StravaAPIError(403, 'Forbidden', errorBody);
      case 404:
        throw new StravaAPIError(404, 'Resource not found', errorBody);
      case 429:
        // No documented Retry-After header; back off until the 15-minute window resets
        throw new StravaAPIError(429, 'Rate limited', errorBody);
      default:
        throw new StravaAPIError(response.status, 'API request failed', errorBody);
    }
  }

  return response.json();
}

// Usage with error handling
try {
  const activity = await stravaFetch(`/activities/${id}`, accessToken);
} catch (error) {
  if (error instanceof StravaAPIError) {
    if (error.status === 401) {
      // Refresh token and retry
      const newToken = await refreshTokens(userId);
      const activity = await stravaFetch(`/activities/${id}`, newToken);
    } else if (error.status === 429) {
      // Schedule retry
      await scheduleRetry(task, 15 * 60 * 1000);
    }
  }
}