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

Code	HTTP	Meaning	Retryable
`VALIDATION_ERROR`	`400`	Invalid input (file type, format, missing field)	No
`AUTH_INVALID_KEY`	`401`	Missing or invalid API key	No
`AUTH_INSUFFICIENT_SCOPE`	`403`	API key lacks required scope	No
`RATE_LIMIT_EXCEEDED`	`429`	Too many requests	Yes
`SERVER_ERROR`	`500`	Internal server error	Yes
`PROVIDER_ERROR`	`502`	All providers failed	Yes
`COST_EXCEEDS_BUDGET`	`402`	Estimated cost exceeds `maxCostUsd`	No
`COST_CONFIRMATION_REQUIRED`	`402`	Cost exceeds confirmation threshold	No
`EXECUTION_ERROR`	`500`	Strategy execution failed	Yes

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
  }
}