speak-common-errors
'Diagnose and fix common Speak API errors: authentication failures, audio
Allowed Tools
ReadWriteEditBash(npm:*)Bash(curl:*)Grep
Provided by Plugin
speak-pack
Claude Code skill pack for Speak AI Language Learning Platform (24 skills)
Installation
This skill is included in the speak-pack plugin:
/plugin install speak-pack@claude-code-plugins-plusClick to copy
Instructions
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 | audioformatinvalid |
Audio not WAV 16kHz mono | Convert with ffmpeg |
| 400 | audiotooshort |
Recording < 0.5 seconds | Record longer audio |
| 400 | audiotoolong |
Recording > 60 seconds | Trim to under 60s |
| 400 | languagenotsupported |
Invalid language code | Use supported codes |
| 401 | invalidapikey |
Wrong or expired key | Regenerate at dashboard |
| 403 | quota_exceeded |
Monthly limit reached | Upgrade plan or wait |
| 404 | sessionnotfound |
Invalid session ID | Start a new session |
| 408 | session_expired |
Session timed out | Sessions expire after 30 min |
| 413 | payloadtoolarge |
Audio file > 25MB | Compress or trim audio |
| 429 | ratelimitexceeded |
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 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 |
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.