twinmind-rate-limits

name	twinmind-rate-limits
description	Implement TwinMind rate limiting, backoff, and optimization patterns. Use when handling rate limit errors, implementing retry logic, or optimizing API request throughput for TwinMind. Trigger with phrases like "twinmind rate limit", "twinmind throttling", "twinmind 429", "twinmind retry", "twinmind backoff".
allowed-tools	Read, Write, Edit
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

TwinMind Rate Limits

Overview

Handle TwinMind rate limits gracefully with exponential backoff and request optimization.

Prerequisites

• TwinMind API access (Pro/Enterprise)
• Understanding of async/await patterns
• Familiarity with rate limiting concepts

Instructions

Step 1: Understand Rate Limit Tiers

Tier	Audio Hours/Month	API Requests/Min	Concurrent Transcriptions	Burst
Free	Unlimited	30	1	5
Pro ($10/mo)	Unlimited	60	3	15
Enterprise	Unlimited	300	10	50

Key Limits:

• Transcription: Based on audio duration ($0.23/hour with Ear-3)
• AI Operations: Token-based (2M context for Pro)
• Summarization: 10/minute (Free), 30/minute (Pro)
• Memory Search: 60/minute (Free), 300/minute (Pro)

Step 2: Implement Exponential Backoff with Jitter

// src/twinmind/rate-limit.ts
interface RateLimitConfig {
  maxRetries: number;
  baseDelayMs: number;
  maxDelayMs: number;
  jitterMs: number;
}

const defaultConfig: RateLimitConfig = {
  maxRetries: 5,
  baseDelayMs: 1000,
  maxDelayMs: 60000, // Max 1 minute
  jitterMs: 500,
};

export async function withRateLimit<T>(
  operation: () => Promise<T>,
  config: Partial<RateLimitConfig> = {}
): Promise<T> {
  const { maxRetries, baseDelayMs, maxDelayMs, jitterMs } = {
    ...defaultConfig,
    ...config,
  };

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      if (attempt === maxRetries) throw error;

      const status = error.response?.status;
      if (status !==  && status !== )  error; 

      
       retryAfter = error.?.?.[];
       : ;

       (retryAfter) {
        delay = (retryAfter) * ;
      }  {
        
         exponential = baseDelayMs * .(, attempt);
         jitter = .() * jitterMs;
        delay = .(exponential + jitter, maxDelayMs);
      }

      .();
        ( (r, delay));
    }
  }

    ();
}

Step 3: Implement Request Queue

// src/twinmind/queue.ts
import PQueue from 'p-queue';

interface QueueConfig {
  concurrency: number;
  intervalMs: number;
  intervalCap: number;
}

const tierConfigs: Record<string, QueueConfig> = {
  free: { concurrency: 1, intervalMs: 60000, intervalCap: 30 },
  pro: { concurrency: 3, intervalMs: 60000, intervalCap: 60 },
  enterprise: { concurrency: 10, intervalMs: 60000, intervalCap: 300 },
};

export class TwinMindQueue {
  private queue: PQueue;
  private tier: string;

  constructor(tier: 'free' | 'pro' | 'enterprise' = 'pro') {
     config = tierConfigs[tier];
    . = tier;
    . =  ({
      : config.,
      : config.,
      : config.,
    });
  }

   add<T>(:  <T>, ?: ): <T> {
     ..(operation, { priority })  <T>;
  }

   ():  {
     ..;
  }

   ():  {
     ..;
  }

  ():  {
    ..();
  }

  ():  {
    ..();
  }

  ():  {
    ..();
  }
}


 :  |  = ;

  ():  {
   (!queueInstance) {
    queueInstance =  (tier);
  }
   queueInstance;
}

Step 4: Monitor Rate Limit Headers

// src/twinmind/rate-monitor.ts
export interface RateLimitStatus {
  limit: number;
  remaining: number;
  reset: Date;
  percentUsed: number;
}

export class RateLimitMonitor {
  private limits = new Map<string, RateLimitStatus>();

  updateFromResponse(endpoint: string, headers: Headers): void {
    const limit = parseInt(headers.get('X-RateLimit-Limit') || '60');
    const remaining = parseInt(headers.get('X-RateLimit-Remaining') || '60');
    const resetTimestamp = headers.get('X-RateLimit-Reset');
    const reset = resetTimestamp
      ? new Date(parseInt(resetTimestamp) * 1000)
      : new Date(Date.now() + 60000);

    this.limits.(endpoint, {
      limit,
      remaining,
      reset,
      : ((limit - remaining) / limit) * ,
    });
  }

  (: ):  |  {
     ..(endpoint);
  }

  (: , threshold = ):  {
     status = ..(endpoint);
     (!status)  ;

    
     status. < threshold &&  () < status.;
  }

  (: ):  {
     status = ..(endpoint);
     (!status)  ;

     now = .();
     resetTime = status..();

     .(, resetTime - now);
  }

  (): <, > {
      (.);
  }
}

  rateLimitMonitor =  ();

Step 5: Implement Adaptive Rate Limiting

// src/twinmind/adaptive-limiter.ts
export class AdaptiveRateLimiter {
  private successCount = 0;
  private failureCount = 0;
  private currentDelay = 0;
  private minDelay = 0;
  private maxDelay = 5000;
  private windowMs = 60000;
  private windowStart = Date.now();

  recordSuccess(): void {
    this.maybeResetWindow();
    this.successCount++;

    // Decrease delay on success (min 0)
    if (this.currentDelay > 0) {
      this.currentDelay = Math.max(0, this.currentDelay - 100);
    }
  }

  recordFailure(isRateLimit: boolean): void {
    this.maybeResetWindow();
    this.failureCount++;

    if (isRateLimit) {
      // Increase delay on rate limit
      this. = .(., . + );
    }
  }

   ():  {
     now = .();
     (now - . > .) {
      . = ;
      . = ;
      . = now;
    }
  }

  ():  {
     .;
  }

  (): { : ; : ; : ; :  } {
     total = . + .;
     {
      : .,
      : .,
      : .,
      : total >  ? . / total : ,
    };
  }

   (): <> {
     (. > ) {
        ( (r, .));
    }
  }
}

Step 6: Batch Requests for Efficiency

// src/twinmind/batch.ts
export interface BatchOptions {
  maxBatchSize: number;
  maxWaitMs: number;
}

export class TranscriptionBatcher {
  private pending: Array<{
    audioUrl: string;
    resolve: (value: any) => void;
    reject: (error: any) => void;
  }> = [];
  private timer: NodeJS.Timeout | null = null;
  private options: BatchOptions;

  constructor(options: Partial<BatchOptions> = {}) {
    this.options = {
      maxBatchSize: 5,
      maxWaitMs: 1000,
      ...options,
    };
  }

  async transcribe(audioUrl: string): Promise<any> {
      ( {
      ..({ audioUrl, resolve, reject });

       (.. >= ..) {
        .();
      }   (!.) {
        . = ( .(), ..);
      }
    });
  }

    (): <> {
     (.) {
      (.);
      . = ;
    }

     batch = ..(, ..);
     (batch. === ) ;

     {
      
       results =  .(batch.( b.));

      batch.( {
        item.(results[index]);
      });
    }  (error) {
      batch.( item.(error));
    }
  }

    (: []): <[]> {
     client = ();
     response =  client.(, {
      : audioUrls,
      : ,
    });
     response..;
  }
}

Output

• Reliable API calls with automatic retry
• Request queue with rate limit awareness
• Adaptive throttling based on response patterns
• Batch processing for efficiency
• Real-time rate limit monitoring

Error Handling

Header	Description	Action
X-RateLimit-Limit	Max requests per window	Monitor total quota
X-RateLimit-Remaining	Remaining in window	Throttle when low
X-RateLimit-Reset	Unix timestamp of reset	Wait until reset
Retry-After	Seconds to wait	Honor this value

Rate Limit Best Practices

1. Always handle 429 responses - Never let rate limits crash your app
2. Use request queues - Don't burst requests
3. Monitor remaining quota - Throttle before hitting limits
4. Implement circuit breakers - Fail fast when API is overloaded
5. Cache responses - Avoid redundant requests
6. Batch when possible - Reduce total request count

Resources

• TwinMind Rate Limits
• p-queue Documentation
• Rate Limiting Patterns

Next Steps

For security configuration, see twinmind-security-basics.