OpenParable
Skip to content
← Back to skills

Speak Common Errors

Testing & Quality
speak-common-errors

Speak Common Errors is an Agent Skill for testing & quality published in the jeremylongshore/claude-code-plugins-plus-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/saas-packs/speak-pack/skills/speak-common-errors/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/speak-common-errors, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

HTTPError CodeDescriptionFix
400audio_format_invalidAudio not WAV 16kHz monoConvert with ffmpeg
400audio_too_shortRecording < 0.5 secondsRecord longer audio
400audio_too_longRecording > 60 secondsTrim to under 60s
400language_not_supportedInvalid language codeUse supported codes
401invalid_api_keyWrong or expired keyRegenerate at dashboard
403quota_exceededMonthly limit reachedUpgrade plan or wait
404session_not_foundInvalid session IDStart a new session
408session_expiredSession timed outSessions expire after 30 min
413payload_too_largeAudio file > 25MBCompress or trim audio
429rate_limit_exceededToo many requestsWait 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

ErrorCauseSolution
401 UnauthorizedInvalid API keyVerify SPEAK_API_KEY environment variable
429 Rate LimitedToo many requestsWait Retry-After seconds, use backoff
Audio format errorWrong codec/sample rateConvert to WAV 16kHz mono with ffmpeg
Session expiredTimeout after 30 minStart 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.