Speak Common Errors

Overview

Diagnose and fix common Speak API errors: authentication failures, audio format issues, rate limits, and session management problems.

Prerequisites

Completed speak-install-auth setup
Valid API credentials configured
ffmpeg installed for audio processing

Instructions

Error Code Reference

HTTP	Error Code	Description	Fix
400	`audio_format_invalid`	Audio not WAV 16kHz mono	Convert with ffmpeg
400	`audio_too_short`	Recording < 0.5 seconds	Record longer audio
400	`audio_too_long`	Recording > 60 seconds	Trim to under 60s
400	`language_not_supported`	Invalid language code	Use supported codes
401	`invalid_api_key`	Wrong or expired key	Regenerate at dashboard
403	`quota_exceeded`	Monthly limit reached	Upgrade plan or wait
404	`session_not_found`	Invalid session ID	Start a new session
408	`session_expired`	Session timed out	Sessions expire after 30 min
413	`payload_too_large`	Audio file > 25MB	Compress or trim audio
429	`rate_limit_exceeded`	Too many requests	Wait `Retry-After` seconds

Quick Diagnostic

# Check API key validity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $SPEAK_API_KEY" \
  https://api.speak.com/v1/languages
# 200 = valid, 401 = invalid, 403 = insufficient permissions

# Check audio format
ffprobe -v quiet -print_format json -show_streams recording.wav \
  | python3 -c "import sys,json; s=json.load(sys.stdin)['streams'][0]; print(f'Rate: {s[\"sample_rate\"]}Hz, Channels: {s[\"channels\"]}')"
# Must be: Rate: 16000Hz, Channels: 1

Error Recovery Pattern

async function resilientSpeakCall<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (err: any) {
      const code = err.response?.data?.error?.code;
      if (code === 'audio_format_invalid') {
        // Auto-convert and retry
        throw new Error('Convert audio to WAV 16kHz mono before retrying');
      }
      if (code === 'session_expired') {
        throw new Error('Session expired — start a new conversation session');
      }
      if (err.response?.status === 429) {
        const wait = parseInt(err.response.headers['retry-after'] || '5');
        await new Promise(r => setTimeout(r, wait * 1000));
        continue;
      }
      throw err;
    }
  }
  throw new Error('Max retries exceeded');
}

Output

Errors implementation complete
Speak API integration verified
Error recovery tested

Error Handling

Error	Cause	Solution
401 Unauthorized	Invalid API key	Verify SPEAK_API_KEY environment variable
429 Rate Limited	Too many requests	Wait Retry-After seconds, use backoff
Audio format error	Wrong codec/sample rate	Convert to WAV 16kHz mono with ffmpeg
Session expired	Timeout after 30 min	Start a new conversation session

Resources

Next Steps

See speak-debug-bundle for diagnostic tools.

Examples

Basic: Apply common errors with default configuration for a standard Speak integration.

Advanced: Customize for production with error recovery, monitoring, and team-specific requirements.

speak-common-errors