Skip to content
Skills Library
Programming · Analysis

speak-common-errors

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

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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

Triggers from the description

speak common errors
Original author description

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

How it works

  1. Overview
  2. Prerequisites
  3. Instructions
  4. Output
  5. Error Handling
  6. Resources
  7. Next Steps
  8. Examples
Original SKILL.md headings · 103 lines, 503 words
SKILL.md preview
---
name: speak-common-errors
description: '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".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(curl:*), Grep
version: 1.14.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- speak
- debugging
compatibility: Designed for Claude Code
---
# 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

```bash
# 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

```typescript
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

- [Speak Website](https://speak.com)
- [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime)
- [Speak GPT-4 Blog](https://speak.com/blog/speak-gpt-4)

## 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.
Files in this package (3)
  • SKILL.md 4 KB
  • references/implementation-guide.md 7 KB
  • references/implementation.md 2 KB

Versions

The database has no other skills named speak-common-errors.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version ca00caa8048f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100speak-rate-limits
    Handle Speak API rate limits with exponential backoff, request queuing, and optimization strategies. Use when implementing rate limits features, or troubleshooting Speak language learning integration issues. Trigger with phrases like "speak rate limits", "speak rate limits".
  • 100speak-debug-bundle
    Collect diagnostic information for Speak API issues: auth verification, audio format validation, session inspection, and network testing. Use when implementing debug bundle features, or troubleshooting Speak language learning integration issues. Trigger with phrases like "speak…
  • 100linear-common-errors
    Diagnose and fix common Linear API errors. Use when encountering Linear API errors, debugging integration issues, or troubleshooting authentication problems. Trigger with phrases like "linear error", "linear API error", "debug linear", "linear not working", "linear authentication error".
  • 100customerio-common-errors
    Diagnose and fix Customer.io common errors. Use when troubleshooting API errors, delivery issues, or integration problems with Customer.io. Trigger with phrases like "customer.io error", "customer.io not working", "debug customer.io", "customer.io issue".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.