Agent skill
speak-common-errors
Diagnose and fix common Speak API errors: authentication failures, audio format issues, rate limits, and session management problems. Use when implementing common errors features, or troubleshooting Speak language learning integration issues. Trigger with phrases like "speak common errors", "speak common errors".
Install this agent skill to your Project
npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/speak-pack/skills/speak-common-errors
SKILL.md
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.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
dockerfile-generator
Dockerfile Generator - Auto-activating skill for DevOps Basics. Triggers on: dockerfile generator, dockerfile generator Part of the DevOps Basics skill category.
branch-naming-helper
Branch Naming Helper - Auto-activating skill for DevOps Basics. Triggers on: branch naming helper, branch naming helper Part of the DevOps Basics skill category.
readme-generator
Readme Generator - Auto-activating skill for DevOps Basics. Triggers on: readme generator, readme generator Part of the DevOps Basics skill category.
makefile-generator
Makefile Generator - Auto-activating skill for DevOps Basics. Triggers on: makefile generator, makefile generator Part of the DevOps Basics skill category.
gitignore-generator
Gitignore Generator - Auto-activating skill for DevOps Basics. Triggers on: gitignore generator, gitignore generator Part of the DevOps Basics skill category.
pre-commit-hook-setup
Pre Commit Hook Setup - Auto-activating skill for DevOps Basics. Triggers on: pre commit hook setup, pre commit hook setup Part of the DevOps Basics skill category.
Didn't find tool you were looking for?