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

# Error handling

> Handle TypeScript SDK errors like ConfigurationError, InputValidationError, RateLimitError, and RequestTimeoutError when running evaluators in your app.

The SDK provides specific error types to help you handle different scenarios.

```typescript example.ts theme={null}
import {
  GradeLevelAppropriatenessEvaluator,
  ConfigurationError
} from "@learning-commons/evaluators";

try {
  const evaluator = new GradeLevelAppropriatenessEvaluator({
    googleApiKey: process.env.GOOGLE_API_KEY,
  });
  const result = await evaluator.evaluate({ text: "The cat's out of the bag now." });
} catch (error) {
  if (error instanceof ConfigurationError) {
    console.error("Fix config:", error.message);
  } else  { ... }
}
```

## Errors

All errors extend `EvaluatorError` and expose a boolean `retryable` flag.

| Type | Description |
| - | - |
| `AuthenticationError` | External system rejected the credentials |
| `ConfigurationError` | Missing or invalid key, unknown provider or model, malformed settings, or a custom provider that can't send images to an evaluator that takes them |
| [`InputValidationError`](#inputvalidationerror) | Invalid input (text too short, invalid grade, an image outside an evaluator's limits, etc.), or a caller-supplied identifier a dependency rejects |
| `KnowledgeGraphError` | Catch-all for Knowledge Graph failures not intercepted by a more specific error (retryable if 5xx) |
| `LLMOutputProcessingError` | Model response failed parsing, normalization, or its output schema; retry immediately |
| `LLMProviderError` | Catch-all for LLM-provider failures not intercepted by a more specific error (retryable if 5xx) |
| `NetworkError` | Network connectivity issues |
| `RateLimitError` | Rate limit exceeded; wait and retry (`retryAfterMs`) |
| `RequestTimeoutError` | Request timed out |
| `StandardNotFoundError` | Standards code does not exist in the jurisdiction (subtype of `InputValidationError`) |

`EvaluatorError`, `EvaluationError`, and [`DependencyError`](#dependencyerror) are abstract. The SDK always raises a concrete subclass.

### `DependencyError`

Describes which external system failed:

| Field | Type | Description |
| :- | :- | :- |
| `dependency` | `"openai" \| "google" \| "anthropic" \| "knowledge-graph" \| "custom"` | Failed system |
| `statusCode` | `number \| null` | HTTP status, when the dependency reported one |
| `requestId` | `string \| null` | Dependency's request id, for support requests |
| `model` | `string \| null` | Model in play, for LLM dependencies |

### `InputValidationError`

[Graphics evaluators](https://docs.learningcommons.org/evaluators/graphics-evaluators/introduction.md) run several checks on each image before any model call:

| Check | Description |
| :- | :- |
| **File** | Image path is a regular file and can be read |
| **Size** | File size falls within the evaluator's limits |
| **Format** | File is a PNG, JPEG, or WebP |
| **Dimensions** | File's width, height, and pixel count fall within evaluator limits |

An image that fails a check raises an `InputValidationError`, which includes a message that names the input and its position:

```text theme={null}
image_paths[0]: "chart.png" is 3000×2000 px; each edge must be 16 to 2560 px. Resize to 2560 px on the long edge before submitting.
```

## Related topics

> [card] [Quickstart](https://docs.learningcommons.org/evaluators/using-evaluators/typescript-sdk/quickstart.md)
>
> Install the SDK and run your first evaluator.

> [card] [Configuration](https://docs.learningcommons.org/evaluators/using-evaluators/typescript-sdk/configuration.md)
>
> Configure evaluators, including API keys and options.

> [card] [Evaluation](https://docs.learningcommons.org/evaluators/using-evaluators/typescript-sdk/evaluation.md)
>
> Understand evaluator output fields and types.

> [card] [Batch evaluator](https://docs.learningcommons.org/evaluators/using-evaluators/typescript-sdk/batch-evaluator.md)
>
> Evaluate a batch of text from a CSV file using Text Complexity evaluators.