Exceptions

All SDK exceptions inherit from CorePlexMLError. Each exception carries three attributes that provide structured error information from the server.

Exception Hierarchy

CorePlexMLError
+-- AuthenticationError  (HTTP 401 / 403)
+-- NotFoundError        (HTTP 404)
+-- ValidationError      (HTTP 422)

Autodoc Reference

exception coreplexml.exceptions.CorePlexMLError(message, status_code=None, detail=None)

Bases: Exception

Base exception for all CorePlexML SDK errors.

Parameters:

• message (str)

• status_code (int | None)

• detail (str | None)

message

Human-readable error message.

status_code

HTTP status code (if applicable).

detail

Detailed error information from the server.

__init__(message, status_code=None, detail=None)

Initialize error.

Parameters:

• message (str) – Error description.

• status_code (Optional[int]) – HTTP status code.

• detail (Optional[str]) – Server error detail.

exception coreplexml.exceptions.AuthenticationError(message, status_code=None, detail=None)

Bases: CorePlexMLError

Raised when authentication fails (HTTP 401 or 403).

This indicates an invalid, expired, or missing API key.

Parameters:

• message (str)

• status_code (int | None)

• detail (str | None)

exception coreplexml.exceptions.NotFoundError(message, status_code=None, detail=None)

Bases: CorePlexMLError

Raised when a resource is not found (HTTP 404).

The requested resource (project, dataset, model, etc.) does not exist or is not accessible to the current user.

Parameters:

• message (str)

• status_code (int | None)

• detail (str | None)

exception coreplexml.exceptions.ValidationError(message, status_code=None, detail=None)

Bases: CorePlexMLError

Raised when input validation fails (HTTP 422).

The request body or parameters did not pass server-side validation.

Parameters:

• message (str)

• status_code (int | None)

• detail (str | None)

CorePlexMLError

class CorePlexMLError(Exception):
    message: str           # Human-readable error message
    status_code: int | None  # HTTP status code (if applicable)
    detail: str | None     # Detailed error info from the server

Base exception for all CorePlexML SDK errors. Raised for any HTTP status code >= 400 that does not map to a more specific subclass.

AuthenticationError

Raised when the server returns HTTP 401 (Unauthorized) or 403 (Forbidden). This typically means the API key is missing, invalid, or expired.

from coreplexml import CorePlexMLClient, AuthenticationError

client = CorePlexMLClient(
    base_url="https://ml.example.com",
    api_key="invalid-key",
)

try:
    client.projects.list()
except AuthenticationError as e:
    print(f"Authentication failed (HTTP {e.status_code}): {e.detail}")
    # Prompt the user to check their API key

NotFoundError

Raised when the server returns HTTP 404. The requested resource (project, dataset, model, etc.) does not exist or is not accessible to the current user.

from coreplexml import CorePlexMLClient, NotFoundError

try:
    client.projects.get("00000000-0000-0000-0000-000000000000")
except NotFoundError as e:
    print(f"Resource not found: {e.detail}")

ValidationError

Raised when the server returns HTTP 422 (Unprocessable Entity). The request body or parameters did not pass server-side validation – for example, an empty project name or an invalid column reference.

from coreplexml import CorePlexMLClient, ValidationError

try:
    client.projects.create("")  # empty name
except ValidationError as e:
    print(f"Validation failed: {e.detail}")

Error Handling Patterns

Catch-All Pattern

Handle all SDK errors with a single except clause:

from coreplexml import CorePlexMLError

try:
    result = client.experiments.create(
        project_id=project_id,
        dataset_version_id=version_id,
        target_column="target",
        problem_type="classification",
    )
except CorePlexMLError as e:
    print(f"API error ({e.status_code}): {e.message}")

Granular Pattern

Handle each error type differently:

from coreplexml import (
    CorePlexMLError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
)

try:
    model = client.models.get(model_id)
    prediction = client.models.predict(model_id, {"feature": 1.0})
except AuthenticationError:
    print("API key is invalid or expired. Regenerate it in Settings > API Keys.")
except NotFoundError:
    print(f"Model {model_id} does not exist or was deleted.")
except ValidationError as e:
    print(f"Invalid input: {e.detail}")
except CorePlexMLError as e:
    print(f"Unexpected error ({e.status_code}): {e.message}")

Retry Pattern

Retry transient errors (5xx) with exponential backoff:

import time
from coreplexml import CorePlexMLError

def predict_with_retry(client, deployment_id, inputs, max_retries=3):
    """Make a prediction with automatic retry on server errors."""
    for attempt in range(max_retries):
        try:
            return client.deployments.predict(deployment_id, inputs)
        except CorePlexMLError as e:
            if e.status_code and e.status_code >= 500 and attempt < max_retries - 1:
                wait = 2 ** attempt  # 1s, 2s, 4s
                print(f"Server error, retrying in {wait}s...")
                time.sleep(wait)
            else:
                raise

result = predict_with_retry(client, deployment_id, {"feature": 1.0})

Timeout Handling

Handle polling timeouts for long-running jobs:

from coreplexml import CorePlexMLError

try:
    result = client.experiments.wait(
        experiment_id,
        interval=10.0,
        timeout=7200.0,  # 2 hours
    )
except CorePlexMLError as e:
    if "timed out" in str(e):
        print("Experiment is still running. Check back later:")
        status = client.experiments.get(experiment_id)
        print(f"  Current status: {status.get('status')}")
    else:
        raise