> ## 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 Python 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.

```python example.py theme={null}
import time

from learning_commons_evaluators import (
  ConfigurationError,
  EvaluatorError,
  GradeLevelAppropriatenessEvaluator,
  RateLimitError,
)

try:
  evaluator = GradeLevelAppropriatenessEvaluator(google_api_key="your-google-key")
except ConfigurationError as error:
  raise SystemExit(error)

for attempt in range(3):
  try:
    result = evaluator.evaluate_sync(text="The cat's out of the bag now.")
    break
  except EvaluatorError as error:
    if not error.retryable or attempt == 2:
      raise
    wait_ms = error.retry_after_ms if isinstance(error, RateLimitError) else None
    time.sleep(wait_ms / 1000 if wait_ms else 2 ** attempt)
```

<Note>
  The SDK already retries internally according to [`max_retries`](/evaluators/sdk-api-reference/python/configuration#options): provider calls, Knowledge Graph requests, and immediate resamples when a model's response fails its output schema. `retryable` tells you whether an error that still reached you is worth another attempt at your level.
</Note>

## 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, or malformed settings |
| `InputValidationError` | Invalid input (text too short, invalid grade, 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 (`retry_after_ms`) |
| `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.

## Dependency errors

Which external system failed is data on the error. Every `DependencyError` carries:

| Attribute | Type | Description |
| :- | :- | :- |
| `dependency` | `"openai" \| "google" \| "anthropic" \| "knowledge-graph" \| "custom"` | Which system failed |
| `status_code` | `int \| None` | HTTP status, when the dependency reported one |
| `request_id` | `str \| None` | The dependency's request id, for support requests |
| `model` | `str \| None` | The model in play, for LLM dependencies |

## Related topics

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/evaluators/getting-started/quickstart#sdk">
    Install the SDK and run your first evaluator.
  </Card>

  <Card title="Configuration" icon="gear" href="/evaluators/sdk-api-reference/python/configuration">
    Configure evaluators, including API keys and options.
  </Card>

  <Card title="Evaluation" icon="table" href="/evaluators/sdk-api-reference/python/evaluation">
    Understand evaluator output fields and types.
  </Card>
</CardGroup>