Error handling

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

example.ts

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`	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 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 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:

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.

Quickstart

Install the SDK and run your first evaluator.

Configuration

Configure evaluators, including API keys and options.

Evaluation

Understand evaluator output fields and types.

Batch evaluator

Evaluate a batch of text from a CSV file using Text Complexity evaluators.

Understanding Evaluators

Getting started

Using Evaluators

Evaluators

Datasets

Resources

Errors

`DependencyError`

`InputValidationError`

Quickstart

Configuration

Evaluation

Batch evaluator

​Errors

​DependencyError

​InputValidationError

​Related topics

Quickstart

Configuration

Evaluation

Batch evaluator

Errors

`DependencyError`

`InputValidationError`

Related topics