Error Handling

All SDK errors extend DecrackleError, which extends the native Error class. Use instanceof checks to handle specific failure modes.

---

Error classes

Class	HTTP Status	Code	When
DecrackleAuthError	401	UNAUTHORIZED	Invalid, expired, or missing API key
DecracklePermissionError	403	varies	Valid key but insufficient plan or scope
DecrackleNotFoundError	404	varies	Job or resource not found
DecrackleValidationError	400 / 413 / 422	varies	Bad input (format, size, language, quota)
DecrackleRateLimitError	429	RATE_LIMIT_EXCEEDED	Too many requests
DecrackleServiceUnavailableError	503	varies	Model or service temporarily down
DecrackleInternalError	500	varies	Unexpected server error
DecrackleNetworkError	0	NETWORK_ERROR	DNS failure, connection refused
DecrackleTimeoutError	0	REQUEST_TIMEOUT	Request exceeded the timeout
DecrackleStreamError	0	varies	Error event received mid-stream

---

Base properties

Every error exposes:

err.message    // Human-readable description
err.status     // HTTP status code (0 for network/timeout errors)
err.code       // Machine-readable error code string
err.requestId  // Decrackle request ID for support (when available)

---

Common validation codes

err.code	Meaning
INVALID_AUDIO_FORMAT	Unsupported file type
FILE_TOO_LARGE	File exceeds plan limit
DURATION_TOO_LONG	Audio exceeds duration limit
STORAGE_QUOTA_EXCEEDED	Account storage quota full
INVALID_LANGUAGE	Unrecognised language code or name
MONTHLY_LIMIT_EXCEEDED	Processing minutes quota exhausted

---

Examples

Handle specific errors

import {
  Decrackle,
  DecrackleAuthError,
  DecrackleValidationError,
  DecrackleRateLimitError,
  DecrackleServiceUnavailableError,
} from '@decrackle/sdk';

try {
  const result = await client.asr.transcribe(audioBuffer);
} catch (err) {
  if (err instanceof DecrackleAuthError) {
    console.error('Check your API key');

  } else if (err instanceof DecrackleValidationError) {
    if (err.code === 'STORAGE_QUOTA_EXCEEDED') {
      console.error('Storage full — delete old jobs to free space');
    } else if (err.code === 'FILE_TOO_LARGE') {
      console.error('File too large for your plan');
    } else {
      console.error('Validation error:', err.message);
    }

  } else if (err instanceof DecrackleRateLimitError) {
    const waitMs = err.retryAfter ?? 5000;
    console.log(`Rate limited — retry in ${waitMs}ms`);
    await new Promise(r => setTimeout(r, waitMs));

  } else if (err instanceof DecrackleServiceUnavailableError) {
    console.error('Service temporarily unavailable, try again later');

  } else {
    throw err; // re-throw unexpected errors
  }
}

Check the request ID for support

try {
  await client.denoise.process(audio);
} catch (err) {
  if (err instanceof DecrackleError) {
    console.error(`Error ${err.code} — request ID: ${err.requestId}`);
    // Share err.requestId with Decrackle support for debugging
  }
}

Rate limit with retryAfter

import { DecrackleRateLimitError } from '@decrackle/sdk';

async function transcribeWithRetry(file: Buffer) {
  while (true) {
    try {
      return await client.asr.transcribe(file);
    } catch (err) {
      if (err instanceof DecrackleRateLimitError) {
        const delay = err.retryAfter ?? 2000;
        await new Promise(r => setTimeout(r, delay));
      } else {
        throw err;
      }
    }
  }
}