Error Handling

Learn how to properly handle errors, implement retry logic, and troubleshoot common issues when using the VoiceDub API.

Error Response Format

All API errors return a consistent JSON structure: Error Response:

{
  "code": "error_code_here",
  "message": "Human-readable error description"
}

HTTP Status Codes

400 Bad Request

Invalid request parameters or malformed data. 400 Examples:

{
  "code": "invalid_arguments",
  "message": "Invalid request parameters or body",
  "errors": {
    "params": "...",
    "query": "...",
    "body": "..."
  }
}

{
  "code": "voice_not_found",
  "message": "Voice not found or not accessible"
}

Common causes:

Invalid UUID format for voice or dub IDs
Missing required parameters
Invalid parameter values (e.g., pitch shift outside -24 to +24 range)
Passing a voiceId for a voice that does not exist or is not accessible

401 Unauthorized

Authentication failed or API key issues. 401 Examples:

{
  "code": "unauthorized",
  "message": "You are not authorized to perform this action"
}

Common causes:

Missing Authorization header
Incorrect API key format (should be Api-Key YOUR_KEY)
Deleted or expired API key

403 Forbidden

Valid request but insufficient permissions or credits. 403 Examples:

{
  "code": "not_enough_credits",
  "message": "Looks like you don't have enough credits! Purchase more at https://voicedub.ai/developer/billing"
}

Common causes:

Insufficient API credits for operation

404 Not Found

Resource doesn’t exist or you don’t have access. 404 Examples:

{
  "code": "not_found",
  "message": "Dub not found"
}

{
  "code": "not_found", 
  "message": "Voice not found"
}

Common causes:

Invalid resource ID

429 Rate Limited

Too many requests in a short time period. 429 Example:

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please wait before making more requests."
}

500 Internal Server Error

Server-side error occurred. 500 Example:

{
  "code": "internal_error",
  "message": "An internal server error occurred. Please try again later."
}

When this happens:

Temporary server issues
Unexpected system errors

Retry Logic

Implement exponential backoff for transient errors:

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      // Don't retry client errors (4xx except 429)
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        const error = await response.json();
        throw new Error(`${error.code}: ${error.message}`);
      }
      
      // Retry server errors (5xx) and rate limits (429)
      if (response.status >= 500 || response.status === 429) {
        if (attempt === maxRetries) {
          throw new Error(`Request failed after ${maxRetries + 1} attempts`);
        }
        
        // Exponential backoff with jitter: 1s-2s, 2s-3s, 4s-5s
        const baseDelay = Math.pow(2, attempt) * 1000;
        const jitter = Math.random() * 1000; // 0-1 second jitter
        const delay = baseDelay + jitter;
        console.log(`Attempt ${attempt + 1} failed, retrying in ${delay.toFixed(0)}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      // Success
      return await response.json();
      
    } catch (error) {
      if (attempt === maxRetries) throw error;
      
      // Exponential backoff with jitter for network errors
      const baseDelay = Math.pow(2, attempt) * 1000;
      const jitter = Math.random() * 1000; // 0-1 second jitter
      const delay = baseDelay + jitter;
      console.log(`Network error, retrying in ${delay.toFixed(0)}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

// Usage
try {
  const data = await apiRequestWithRetry('https://api.voicedub.ai/v1/me', {
    headers: { 'Authorization': `Api-Key ${apiKey}` }
  });
  console.log('Success:', data);
} catch (error) {
  console.error('Failed after retries:', error.message);
}

Status Polling Best Practices

When polling for job completion, follow these guidelines:

Polling Intervals

Never poll faster than once every 3 seconds to avoid rate limiting.

async function pollDubStatus(dubId, maxWaitTime = 600000) { // 10 minutes max
  const startTime = Date.now();
  
  while (Date.now() - startTime < maxWaitTime) {
    const response = await fetch(`https://api.voicedub.ai/v1/me/dubs/${dubId}`, {
      headers: { 'Authorization': `Api-Key ${apiKey}` }
    });
    
    if (!response.ok) {
      throw new Error(`Poll failed: ${response.status}`);
    }
    
    const dub = await response.json();
    
    if (dub.status === 'done') {
      return dub; // Success!
    }
    
    if (dub.status === 'error') {
      throw new Error(`Dub failed: ${dub.errorMessage}`);
    }
    
    // Wait 3 seconds before next poll
    await new Promise(resolve => setTimeout(resolve, 3000));
  }
  
  throw new Error('Polling timeout - job did not complete in time');
}

Common Error Scenarios

Scenario 1: Insufficient Credits

Detection

{
  "code": "not_enough_credits",
  "message": "Looks like you don't have enough credits! Purchase more at https://voicedub.ai/developer/billing"
}

Resolution

Check current credit balance with GET /v1/me
Purchase more credits or enable auto top-up
Retry the request once credits are available

Prevention

Monitor credit balance regularly
Set up auto top-up with appropriate thresholds
Check requiredCredits after preprocessing before generation
Implement credit balance checks in your application

Scenario 2: Processing Failures

Detection

{
  "status": "error",
  "errorCode": "processing_failed",
  "errorMessage": "Audio processing failed - invalid format or corrupted file"
}

Resolution

Check audio file format and quality
Try a different audio file or format
Ensure file is not corrupted
Verify file size is under 50MB
Check if audio contains detectable vocals

Prevention

Use high-quality source audio (192kbps+ MP3 or lossless)
Test with shorter clips first
Validate file format before upload
Use supported formats: MP3, WAV, M4A, FLAC, OGG

Scenario 3: Rate Limiting

Detection

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please wait before making more requests."
}

Resolution

Implement exponential backoff
Wait before retrying (start with 1 second)
Reduce request frequency

Prevention

Implement request queuing in your application
Don’t poll faster than once every 3 seconds
Cache responses when appropriate

Error Handling Checklist

✅ Implement proper HTTP status code handling

✅ Parse error responses for specific error codes

✅ Implement exponential backoff for retries

✅ Set appropriate timeouts for long-running operations

✅ Don’t retry 4xx errors (except 429)

✅ Log errors for debugging and monitoring

✅ Provide meaningful error messages to users

✅ Monitor credit balance and handle insufficient credits gracefully

Debugging Tips

Enable Request Logging

Log all API requests and responses for debugging:

const apiCall = async (url, options) => {
  console.log('API Request:', { url, options });
  
  const response = await fetch(url, options);
  const data = await response.json();
  
  console.log('API Response:', { 
    status: response.status, 
    data 
  });
  
  return { response, data };
};

Common Debugging Steps

Verify API key format: Should be Api-Key YOUR_API_KEY
Check request payload: Ensure JSON is valid and complete
Validate UUIDs: Voice and dub IDs must be valid UUID format
Test with cURL: Isolate issues by testing with cURL first
Check network connectivity: Ensure you can reach api.voicedub.ai

Getting Help

When contacting support, include:

Dub/Voice ID
Complete error response with code and message
Steps to reproduce the issue
Audio file details (format, size, duration)
Timestamp when the error occurred

Need help debugging an issue? Join our Discord community or email help@voicedub.ai with the details above.

Getting Started

Core Features

Advanced Topics

Error Response Format

HTTP Status Codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Rate Limited

500 Internal Server Error

Retry Logic

Status Polling Best Practices

Polling Intervals

Common Error Scenarios

Scenario 1: Insufficient Credits

Scenario 2: Processing Failures

Scenario 3: Rate Limiting

Error Handling Checklist

Debugging Tips

Enable Request Logging

Common Debugging Steps

Getting Help

Getting Started

Core Features

Advanced Topics

Documentation Index

​Error Response Format

​HTTP Status Codes

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​429 Rate Limited

​500 Internal Server Error

​Retry Logic

​Status Polling Best Practices

​Polling Intervals

​Common Error Scenarios

​Scenario 1: Insufficient Credits

​Scenario 2: Processing Failures

​Scenario 3: Rate Limiting

​Error Handling Checklist

​Debugging Tips

​Enable Request Logging

​Common Debugging Steps

​Getting Help

Error Response Format

HTTP Status Codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Rate Limited

500 Internal Server Error

Retry Logic

Status Polling Best Practices

Polling Intervals

Common Error Scenarios

Scenario 1: Insufficient Credits

Scenario 2: Processing Failures

Scenario 3: Rate Limiting

Error Handling Checklist

Debugging Tips

Enable Request Logging

Common Debugging Steps

Getting Help