> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

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

# Errors

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

## Error shape

```json theme={null}
{
  "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:

```js theme={null}
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.

```js theme={null}
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
  }
}
```