Diagnose and fix common Speak API errors: authentication failures, audio format issues, rate limits, and session management problems.
speak-install-auth setup| 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 |
# 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: 1async 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');
}| Error | Cause | Solution |
|---|---|---|
| 401 Unauthorized | Invalid API key | Verify SPEAKAPIKEY 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 |
See speak-debug-bundle for diagnostic tools.
Basic: Apply common errors with default configuration for a standard Speak integration.
Advanced: Customize for production with error recovery, monitoring, and team-specific requirements.