Skip to main content

​
Errors

Docex returns structured errors with codes, retryability hints, and actionable suggestions. All errors use the DocexError shape.

​
Error shape

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Unsupported file type \"gif\". Supported types: jpeg, jpg, png, heic, pdf.",
    "status": 400,
    "suggestion": "Convert the file to a supported format and retry.",
    "retryable": false,
    "params": { "fileType": "gif", "allowedFileTypes": ["jpeg", "jpg", "png", "heic", "pdf"] }
  }
}

​
Error codes

CodeHTTPMeaningRetryable
VALIDATION_ERROR400Invalid input (file type, format, missing field)No
AUTH_INVALID_KEY401Missing or invalid API keyNo
AUTH_INSUFFICIENT_SCOPE403API key lacks required scopeNo
RATE_LIMIT_EXCEEDED429Too many requestsYes
SERVER_ERROR500Internal server errorYes
PROVIDER_ERROR502All providers failedYes
COST_EXCEEDS_BUDGET402Estimated cost exceeds maxCostUsdNo
COST_CONFIRMATION_REQUIRED402Cost exceeds confirmation thresholdNo
EXECUTION_ERROR500Strategy execution failedYes

​
Retry behavior

The SDK automatically retries on retryable errors (retryable: true) with exponential backoff. For manual retry logic: 
if (error.code === "RATE_LIMIT_EXCEEDED") {
  await sleep(2000);
  return retry();
}

if (error.code === "PROVIDER_ERROR") {
  // Automatic fallback already attempted by the worker
  // Wait and retry the entire run
  await sleep(5000);
  return retry();
}

​
Client-side errors

The SDK throws DocexError instances for client-side validation failures (unsupported file types, invalid output formats) before making any API request. 
import { DocexError } from "docexdev";

try {
  await docex.run({ file: "image.gif", prompt: "..." });
} catch (err) {
  if (err instanceof DocexError) {
    console.log(err.code);        // "VALIDATION_ERROR"
    console.log(err.suggestion);  // "Convert the file to a supported format and retry."
    console.log(err.retryable);   // false
  }
}