Twinmind Common Errors

Error: Authentication failed - Invalid or expired API key
Status: 401 Unauthorized  # HTTP 401 Unauthorized

set -euo pipefail
# Verify API key is set correctly
echo $TWINMIND_API_KEY

# Test authentication
curl -H "Authorization: Bearer $TWINMIND_API_KEY" \
  https://api.twinmind.com/v1/health

# Regenerate key if expired
# Visit: https://twinmind.com/settings/api

Error: Microphone permission denied
NotAllowedError: Permission denied

1. Click lock icon in address bar
2. Site Settings > Microphone > Allow
3. Reload the page

# Check current permissions
tccutil list com.google.Chrome

# Reset permissions (requires re-grant)
tccutil reset Microphone com.google.Chrome

Settings > Privacy > Microphone > Allow apps to access microphone

Error: Transcription timeout after 300000ms
RequestTimeoutError: Request exceeded timeout

// Increase timeout for large files
const client = new TwinMindClient({
  apiKey: process.env.TWINMIND_API_KEY,
  timeout: 600000, // 10 minutes  # 600000 = configured value
});

// Or use async processing with webhooks
const response = await client.post('/transcribe', {
  audio_url: audioUrl,
  async: true,
  webhook_url: 'https://your-server.com/webhook/twinmind',
});

Error: Rate limit exceeded. Please retry after 60 seconds.
Status: 429 Too Many Requests  # HTTP 429 Too Many Requests
X-RateLimit-Remaining: 0

// Implement exponential backoff
async function withBackoff<T>(operation: () => Promise<T>): Promise<T> {
  const maxRetries = 5;
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      if (error.response?.status !== 429) throw error;  # HTTP 429 Too Many Requests

      const retryAfter = parseInt(error.response.headers['retry-after'] || '60');
      console.log(`Rate limited. Waiting ${retryAfter}s...`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));  # 1000: 1 second in ms
    }
  }
  throw new Error('Max retries exceeded');
}

Error: Unsupported audio format
AudioFormatError: Format 'xyz' is not supported

# Convert to supported format using ffmpeg
ffmpeg -i input.xyz -acodec libmp3lame -q:a 2 output.mp3

# Supported formats: MP3, WAV, M4A, WebM, OGG, FLAC

Error: No audio detected in input
TranscriptionError: Empty or silent audio

# Check audio file properties
ffprobe -i audio.mp3 -show_streams -select_streams a

# Check audio levels
ffmpeg -i audio.mp3 -filter:a volumedetect -f null /dev/null

# Amplify quiet audio
ffmpeg -i quiet.mp3 -filter:a "volume=2.0" amplified.mp3

Error: Speaker diarization failed
DiarizationError: Unable to identify distinct speakers

// Retry without diarization
const transcript = await client.transcribe(audioUrl, {
  diarization: false, // Disable diarization
});

// Or provide speaker count hint
const transcript = await client.transcribe(audioUrl, {
  diarization: true,
  expected_speakers: 3, // Help the model
});

Error: Calendar sync failed
OAuth2Error: Token expired or revoked

1. Open TwinMind extension
2. Go to Settings > Integrations
3. Click "Disconnect" for calendar
4. Click "Connect" to re-authorize
5. Grant all requested permissions

Error: Summary generation failed
GenerationError: Transcript too short for summarization

// Check transcript length before summarization
const minWordsForSummary = 50;
const wordCount = transcript.text.split(/\s+/).length;

if (wordCount < minWordsForSummary) {
  console.log('Transcript too short for summary');
  return null;
}

const summary = await client.summarize(transcript.id);