jeremylongshore 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-authsetup - 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.
Source: jeremylongshore/claude-code-plugins-plus-skills → skills/.curated/speak-common-errors/SKILL.md
Also appears in: jeremylongshore/claude-code-plugins-plus-skills/plugins/saas-packs/speak-pack/skills/speak-common-errors/SKILL.md