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

# Error Reference

This page provides a complete reference for all error codes and exceptions you may encounter when using the AI Guard SDK and REST API.

## HTTP Error Codes

### Classification Endpoint (`POST /classifications/v1`)

| HTTP Status | Error Code            | Description                        | Common Cause                                                            |
| ----------- | --------------------- | ---------------------------------- | ----------------------------------------------------------------------- |
| `200`       | —                     | Successful classification          | —                                                                       |
| `400`       | Bad Request           | Invalid request body or parameters | Malformed classifier description, missing required fields               |
| `401`       | Unauthorized          | Authentication failed              | Invalid, expired, or missing bearer token                               |
| `500`       | Internal Server Error | Server-side error                  | Classification engine failure                                           |
| `502`       | Bad Gateway           | Upstream service unavailable       | `scan-job-manager` not reachable or classification profiles unavailable |

### Metrics Endpoint (`POST /metric`)

| HTTP Status | Error Code   | Description                              | Common Cause                                                 |
| ----------- | ------------ | ---------------------------------------- | ------------------------------------------------------------ |
| `200`       | —            | Metric recorded successfully             | —                                                            |
| `400`       | Bad Request  | Metrics not permitted or invalid request | Metrics disabled in config, or invalid meter name/attributes |
| `401`       | Unauthorized | Authentication failed                    | Invalid, expired, or missing bearer token                    |

### Health Endpoint (`GET /health`)

| HTTP Status | Description                  |
| ----------- | ---------------------------- |
| `200`       | Service is healthy and ready |

## Error Response Format

All error responses use the following JSON structure:

```json
{
  "code": 400,
  "message": "Description of the error"
}
```

| Field     | Type      | Description                      |
| --------- | --------- | -------------------------------- |
| `code`    | `integer` | HTTP status code                 |
| `message` | `string`  | Human-readable error description |

## SDK Exceptions

The Python SDK maps HTTP error codes to Python exceptions:

| HTTP Status | Python Exception  | Description                                           |
| ----------- | ----------------- | ----------------------------------------------------- |
| `400`       | `ValueError`      | Invalid request — check the error message for details |
| `401`       | `PermissionError` | Authentication failed — verify your API key           |
| `500+`      | `RuntimeError`    | Server error — check service logs                     |
| Other       | `RuntimeError`    | Unexpected error                                      |

### Exception Handling Pattern

```python
from ai_guard import AIGuardClient
from ai_guard.api import (
    AIPlatform, ClassificationRequest, ClassifierDescriptionDefault,
    MetricsEvent, MetricsEventMeter,
)

client = AIGuardClient(
    "https://ai-guard.example.com:4443",
    token="your-api-key",
    agent_id="my-agent",
    platform=AIPlatform.AMAZON_BEDROCK,
)

# Classification errors
try:
    response = client.classify(ClassificationRequest(
        context={"actor": "user"},
        classifier_description=ClassifierDescriptionDefault(),
        text="test text",
    ))
except ValueError as e:
    # 400: Bad request — fix the request parameters
    print(f"Invalid request: {e}")
except PermissionError as e:
    # 401: Authentication failed — check your API key
    print(f"Auth failed: {e}")
except RuntimeError as e:
    # 500+: Server error — check service logs
    print(f"Server error: {e}")

# Metrics errors
try:
    client.metric(MetricsEvent(
        attributes={"new_session": "true"},
        meter=MetricsEventMeter(name="ai_guard.user", value="1"),
    ))
except ValueError as e:
    # 400: Metrics not enabled or invalid request
    print(f"Metrics error: {e}")
except PermissionError as e:
    # 401: Authentication failed
    print(f"Auth failed: {e}")
except RuntimeError as e:
    # Other error
    print(f"Error: {e}")
```

## Client Construction Errors

| Error                      | Cause                                          | Resolution                                 |
| -------------------------- | ---------------------------------------------- | ------------------------------------------ |
| `ValueError` (pin\_sha256) | Invalid base64 encoding or digest not 32 bytes | Re-extract the pin using openssl commands  |
| `ConnectionError`          | Cannot reach the AI Guard service              | Verify URL, port, and network connectivity |

## Common Error Scenarios

### "Metrics not permitted"

**HTTP 400** on `POST /metric`

The `metrics` section is not configured in the AI Guard service configuration file. Contact your administrator to enable metrics.

### "Invalid or missing bearer token"

**HTTP 401** on any authenticated endpoint

* Verify the API key is correct
* Ensure the key has **Data Discovery** scope
* Check that the token validation endpoint is reachable (for OneTrust auth mode)

### "Classification engine error"

**HTTP 500** on `POST /classifications/v1`

An internal error occurred in the classification engine. Check the service logs (`RUST_LOG=debug`) for details.

### "Upstream classification service unavailable"

**HTTP 502** on `POST /classifications/v1`

The AI Guard service cannot reach the scan job manager for classification profiles. Verify:

* `JOB_EXECUTOR_BASE_URL` is configured correctly
* The `scan-job-manager` service is running and reachable

## What's Next?

* [Troubleshooting](https://developer.onetrust.com/onetrust/docs/ai-guard-troubleshooting) — Step-by-step diagnostic guides
* [FAQ](https://developer.onetrust.com/onetrust/docs/ai-guard-faq) — Frequently asked questions