Skip to main content

Error Handling

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


Error classes​

ClassHTTP StatusCodeWhen
DecrackleAuthError401UNAUTHORIZEDInvalid, expired, or missing API key
DecracklePermissionError403variesValid key but insufficient plan or scope
DecrackleNotFoundError404variesJob or resource not found
DecrackleValidationError400 / 413 / 422variesBad input (format, size, language, quota)
DecrackleRateLimitError429RATE_LIMIT_EXCEEDEDToo many requests
DecrackleServiceUnavailableError503variesModel or service temporarily down
DecrackleInternalError500variesUnexpected server error
DecrackleNetworkError0NETWORK_ERRORDNS failure, connection refused
DecrackleTimeoutError0REQUEST_TIMEOUTRequest exceeded the timeout
DecrackleStreamError0variesError 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.codeMeaning
INVALID_AUDIO_FORMATUnsupported file type
FILE_TOO_LARGEFile exceeds plan limit
DURATION_TOO_LONGAudio exceeds duration limit
STORAGE_QUOTA_EXCEEDEDAccount storage quota full
INVALID_LANGUAGEUnrecognised language code or name
MONTHLY_LIMIT_EXCEEDEDProcessing 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;
}
}
}
}