Skip to main content

Error Handling

Robust error handling ensures your application recovers gracefully from API failures. This guide covers common patterns for handling AudioSpliter errors.

Error Response Format​

All errors return a consistent JSON structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "status": 400,
    "details": {}
  }
}

Handling HTTP Errors​

Node.js​

async function createSplitJob(sourceUrl) {
  const response = await fetch('https://api.audiospliter.com/api/v1/splits', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.AUDIOSPLITER_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sourceUrl,
      splitMode: 'duration',
      segmentDuration: 600,
    }),
  });

  if (!response.ok) {
    const { error } = await response.json();

    switch (error.status) {
      case 401:
        throw new Error('Invalid API key. Check your AUDIOSPLITER_API_KEY.');
      case 413:
        throw new Error('File too large for your plan. Upgrade or use a smaller file.');
      case 429:
        // Rate limited - wait and retry
        const retryAfter = error.retryAfter || 30;
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        return createSplitJob(sourceUrl); // Retry
      default:
        throw new Error(`API error ${error.code}: ${error.message}`);
    }
  }

  return response.json();
}

Python​

import requests
import time
import os

def create_split_job(source_url: str, retries: int = 3):
    for attempt in range(retries):
        response = requests.post(
            'https://api.audiospliter.com/api/v1/splits',
            headers={'X-API-Key': os.environ['AUDIOSPLITER_API_KEY']},
            json={
                'sourceUrl': source_url,
                'splitMode': 'duration',
                'segmentDuration': 600,
            },
        )

        if response.status_code == 429:
            retry_after = response.json().get('error', {}).get('retryAfter', 30)
            time.sleep(retry_after)
            continue

        response.raise_for_status()
        return response.json()

    raise Exception('Max retries exceeded')

Handling Job Failures​

Jobs can fail during processing. Check for failures when polling:

const job = await fetch(`https://api.audiospliter.com/api/v1/splits/${jobId}`, {
  headers: { 'X-API-Key': apiKey },
}).then(r => r.json());

if (job.status === 'failed') {
  console.error(`Job failed: ${job.error.code} - ${job.error.message}`);
  // Decide whether to retry based on the error code
  if (['DOWNLOAD_FAILED', 'CORRUPT_FILE'].includes(job.error.code)) {
    // Do not retry - the source file is the problem
  } else {
    // Transient error - safe to retry
  }
}

Retry Strategy​

Use exponential backoff with jitter for retries:

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function withRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      const delay = Math.min(1000 * 2 ** attempt + Math.random() * 1000, 30000);
      await sleep(delay);
    }
  }
}

See Also​