AI Guard: 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:

{
  "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

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 — Step-by-step diagnostic guides
FAQ — Frequently asked questions