Speak common errors

Skill jeremylongshore/claude-code-plugins-plus-skills/plugins/saas-packs/speak-pack/skills/speak-common-errors

425 plugins, 2,810 skills, 200 agents for Claude Code. Open-source marketplace at tonsofskills.com with the ccpi CLI package manager.

Install

npx -y skills add jeremylongshore/claude-code-plugins-plus-skills --skill speak-common-errors

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

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

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

4.1 KB, as published. Nobody here has run it

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.