speak-common-errors

Speak Common Errors

Overview

Quick reference for the top 10 most common Speak errors and their solutions.

Prerequisites

• Speak SDK installed
• API credentials configured
• Access to error logs

Instructions

Step 1: Identify the Error

Check error message and code in your logs or console.

Step 2: Find Matching Error Below

Match your error to one of the documented cases.

Step 3: Apply Solution

Follow the solution steps for your specific error.

Error Reference

1. Authentication Failed

Error Message:

SpeakAuthError: Invalid API key or App ID
Code: AUTH_001

Cause: API key is missing, expired, or invalid. App ID mismatch.

Solution:

# Verify API key is set
echo $SPEAK_API_KEY
echo $SPEAK_APP_ID

# Test authentication
curl -X POST https://api.speak.com/v1/health \
  -H "Authorization: Bearer ${SPEAK_API_KEY}" \
  -H "X-App-ID: ${SPEAK_APP_ID}"

---

2. Rate Limit Exceeded

Error Message:

SpeakRateLimitError: Rate limit exceeded. Retry after 60 seconds.
Code: RATE_001
Headers: X-RateLimit-Reset: 1699876543

Cause: Too many API requests in a short period.

Solution: Implement exponential backoff. See speak-rate-limits skill.

// Quick fix: Add delay between requests
await new Promise(resolve => setTimeout(resolve, 1000));

---

3. Audio Processing Failed

Error Message:

SpeakAudioError: Invalid audio format or corrupted audio data
Code: AUDIO_001

Cause: Audio file is in wrong format, too short, or corrupted.

Solution:

// Validate audio before sending
function validateAudio(audioData: ArrayBuffer): boolean {
  // Check minimum length (0.5 seconds at 16kHz = 16000 samples)
  if (audioData.byteLength < 16000) {
    console.error('Audio too short');
    return false;
  }

  // Check format (WAV header magic number)
  const view = new DataView(audioData);
  const magic = String.fromCharCode(
    view.getUint8(0), view.getUint8(1),
    view.getUint8(2), view.getUint8(3)
  );
  if (magic !== 'RIFF') {
    console.error('Invalid audio format (expected WAV)');
    return false;
  }

  return true;
}

Supported formats:

• WAV (PCM, 16-bit, mono, 16kHz) - Recommended
• MP3 (128kbps minimum)
• WebM (Opus codec)

---

4. Session Expired

Error Message:

SpeakSessionError: Session expired or not found
Code: SESSION_001
SessionId: sess_abc123

Cause: Lesson session timed out or was ended.

Solution:

// Check session status before operations
async function safeSessionOperation(
  session: LessonSession,
  operation: () => Promise<any>
) {
  const status = await session.getStatus();

  if (status === 'expired' || status === 'ended') {
    // Start new session
    console.log('Session expired, starting new session...');
    return await startNewSession();
  }

  return await operation();
}

---

5. Language Not Supported

Error Message:

SpeakLanguageError: Language 'xyz' is not supported
Code: LANG_001

Cause: Requested language code is invalid or not available.

Solution:

const SUPPORTED_LANGUAGES = [
  'en', 'es', 'fr', 'de', 'pt-BR',
  'ko', 'ja', 'zh-TW', 'zh-CN', 'id'
];

function validateLanguage(lang: string): boolean {
  if (!SUPPORTED_LANGUAGES.includes(lang)) {
    console.error(`Unsupported language: ${lang}`);
    console.log(`Supported: ${SUPPORTED_LANGUAGES.join(', ')}`);
    return false;
  }
  return true;
}

---

6. Speech Recognition Failed

Error Message:

SpeakRecognitionError: Could not recognize speech
Code: RECOGNITION_001
Confidence: 0.12

Cause: Audio quality too poor, background noise, or unclear speech.

Solution:

// Check recognition confidence
async function recognizeWithRetry(
  client: SpeakClient,
  audioData: ArrayBuffer,
  minConfidence: number = 0.5
): Promise<RecognitionResult> {
  const result = await client.speech.recognize(audioData);

  if (result.confidence < minConfidence) {
    console.log('Low confidence. Please try again with clearer speech.');
    throw new Error('Recognition confidence too low');
  }

  return result;
}

Tips for better recognition:

• Use a high-quality microphone
• Reduce background noise
• Speak clearly and at normal pace
• Maintain consistent distance from mic

---

7. Network Timeout

Error Message:

SpeakNetworkError: Request timeout after 30000ms
Code: NETWORK_001

Cause: Network connectivity or server latency issues.

Solution:

// Increase timeout for large audio files
const client = new SpeakClient({
  apiKey: process.env.SPEAK_API_KEY!,
  appId: process.env.SPEAK_APP_ID!,
  timeout: 60000, // 60 seconds
  retries: 3,
});

---

8. Quota Exceeded

Error Message:

SpeakQuotaError: Monthly API quota exceeded
Code: QUOTA_001
Usage: 100000/100000

Cause: Exceeded monthly API call limit for your plan.

Solution:

// Monitor usage before operations
async function checkQuota(client: SpeakClient): Promise<boolean> {
  const usage = await client.account.getUsage();

  console.log(`Usage: ${usage.current}/${usage.limit}`);
  console.log(`Remaining: ${usage.remaining}`);

  if (usage.remaining < 100) {
    console.warn('Low quota warning!');
  }

  return usage.remaining > 0;
}

---

9. Invalid Response Format

Error Message:

SpeakParseError: Invalid response from AI tutor
Code: PARSE_001

Cause: AI tutor returned unexpected response format.

Solution:

// Validate tutor responses
function validateTutorResponse(response: any): TutorResponse {
  const required = ['text', 'type'];

  for (const field of required) {
    if (!(field in response)) {
      throw new Error(`Missing required field: ${field}`);
    }
  }

  return response as TutorResponse;
}

---

10. Concurrent Session Limit

Error Message:

SpeakLimitError: Maximum concurrent sessions reached
Code: LIMIT_001
MaxSessions: 5
CurrentSessions: 5

Cause: Too many active sessions for your account.

Solution:

// Clean up old sessions before starting new ones
async function ensureSessionSlot(
  client: SpeakClient
): Promise<void> {
  const sessions = await client.sessions.list({ status: 'active' });

  if (sessions.length >= 5) {
    // End oldest session
    const oldest = sessions.sort((a, b) =>
      a.createdAt.getTime() - b.createdAt.getTime()
    )[0];

    await oldest.end();
    console.log(`Ended old session: ${oldest.id}`);
  }
}

Quick Diagnostic Commands

# Check Speak service status
curl -s https://status.speak.com/api/status | jq

# Verify API connectivity
curl -X POST https://api.speak.com/v1/health \
  -H "Authorization: Bearer ${SPEAK_API_KEY}" \
  -H "X-App-ID: ${SPEAK_APP_ID}"

# Check local configuration
env | grep SPEAK

# List active sessions (if CLI available)
speak sessions list --status active

Escalation Path

1. Collect evidence with speak-debug-bundle
2. Check Speak status page: https://status.speak.com
3. Contact support with request ID from error

Resources

• Speak Status Page
• Speak Support
• Speak Error Codes

Next Steps

For comprehensive debugging, see speak-debug-bundle.