​

Plaid API Rate Limit Handling

​

Rate Limit Context

1. Per-Item Rate Limit: 5 requests per minute per item
2. Global Client Rate Limit: 1,200 requests per minute across all items

​

Implementation Strategy

​

1. Routes with Rate Limit Protection

• /app/api/fetch-balances/route.ts - User-triggered balance updates
• /app/api/connect-bank/route.ts - Initial bank connection
• /app/api/relink/route.ts - Account re-authentication
• /app/api/cron/schedule-portfolio-briefs/process-portfolio-brief/route.ts - Portfolio brief generation
• /app/api/cron/daily-snapshots/route.ts - End-of-day snapshots
• /app/api/plaid/webhook/route.ts - Webhook processing

​

2. Rate Limit Detection

const isRateLimitError =
  error.response?.status === 429 ||
  errorCode === 'RATE_LIMIT_EXCEEDED' ||
  errorType === 'RATE_LIMIT_EXCEEDED';

​

3. Prevention Strategies

​

3.1 Global Delay Between Requests

// Simple global rate limiting
const GLOBAL_REQUEST_DELAY = 250; // ms delay between Plaid API calls

// Implementation
await new Promise(resolve => setTimeout(resolve, GLOBAL_REQUEST_DELAY));

• 240 requests per minute (60,000ms ÷ 250ms)
• Well below Plaid’s 1,200/minute global limit

​

3.2 Staleness Checks

• User-Triggered Updates: Uses client-side Map to track last update time with 60-second window
• Portfolio Brief: Checks if balance was updated in last 30 minutes
• Daily Snapshots: Checks if balance was updated today

​

4. Reactive Strategies

​

4.1 Fixed Retry with Backoff (Daily Snapshots)

// Fixed delay for rate limit retries
const RATE_LIMIT_RETRY_DELAY = 25000; // 25 seconds
const MAX_RETRIES = 3;

// When rate limited:
if (isRateLimitError) {
  // Wait 25 seconds before retry
  await new Promise(resolve => setTimeout(resolve, RATE_LIMIT_RETRY_DELAY));
}

​

4.2 Exponential Backoff with Jitter (Portfolio Brief)

// For retryable errors including rate limits
const baseDelay = RETRY_DELAY * Math.pow(2, attempts - 1); // Exponential growth
const jitter = Math.random() * 0.5 * baseDelay; // Add randomness
const delay = baseDelay + jitter;

​

5. ITEM_LOGIN_REQUIRED Handling

if (errorCode === 'ITEM_LOGIN_REQUIRED') {
  // Update the item as expired in the database
  await supabaseClient
    .from('items')
    .update({ is_expired: true })
    .eq('item_id', item.item_id);
    
  // Skip further processing for this item
}

​

Effectiveness

1. Per-Item Limit: Handled by appropriate delays between retries
2. Global Limit: Managed by small delays between all requests
3. Expired Items: Properly marked in database for user notification