Exceptions

Reference

Exceptions

Error handling and exception hierarchy

10 min Intermediate

ReferenceAPIErrors

Exceptions

The SDK defines a structured exception hierarchy rooted at GraphOLAPError. Every API error is mapped to a specific exception class, making it easy to handle different failure modes with standard try/except patterns.

All exceptions carry a human-readable .message and many include a .details dict with machine-readable context (status codes, resource IDs, limits, etc.).

1

Setup

Connect to the platform

# Cell 1 — Parameters
USERNAME = "_FILL_ME_IN_"  # Set your email before running

# Cell 2 — Connect
from graph_olap import GraphOLAPClient
client = GraphOLAPClient(username=USERNAME)

# Cell 3 — Provision
from notebook_setup import provision
personas, _ = provision(USERNAME)
analyst = personas["analyst"]
admin = personas["admin"]
ops = personas["ops"]
client = analyst

import graph_olap.exceptions as exc

2

Exception Hierarchy

The full class tree

All SDK exceptions inherit from GraphOLAPError, which itself extends Python’s built-in Exception.

GraphOLAPError
  ├── AuthenticationError
  ├── PermissionDeniedError
  │     └── ForbiddenError
  ├── NotFoundError
  ├── ValidationError
  ├── ConflictError
  │     ├── ResourceLockedError
  │     ├── ConcurrencyLimitError
  │     ├── DependencyError
  │     └── InvalidStateError
  ├── TimeoutError
  │     ├── QueryTimeoutError
  │     └── AlgorithmTimeoutError
  ├── RyugraphError
  ├── AlgorithmNotFoundError
  ├── AlgorithmFailedError
  ├── SnapshotFailedError
  ├── InstanceFailedError
  └── ServerError
        └── ServiceUnavailableError

Catching GraphOLAPError will catch every SDK exception. Catch more specific subclasses first when you need differentiated handling.

3

Catching Specific Exceptions

Try/except patterns for common errors

NotFoundError

Raised when a requested resource does not exist (HTTP 404).

try:
    client.instances.get(999999)
except exc.NotFoundError as e:
    print(f"Caught NotFoundError: {e}")
    print(f"Details: {e.details}")

ValidationError

Raised when request parameters fail server-side validation (HTTP 422).

try:
    client.instances.create(
        mapping_id=-1,
        name="",
        wrapper_type="falkordb",
    )
except exc.ValidationError as e:
    print(f"Caught ValidationError: {e}")
    print(f"Details: {e.details}")

Accessing exception attributes

Most exceptions expose:

Attribute	Type	Description
args[0]	str	The error message (also returned by str(e))
.details	dict	Machine-readable context (present on most subclasses)

Some subclasses add convenience properties. For example, ConcurrencyLimitError exposes .current_count, .max_allowed, and .limit_type.

# Demonstrate attribute access on a caught exception
try:
    client.instances.get(999999)
except exc.NotFoundError as e:
    print(f"Message:     {e}")
    print(f"Details:     {e.details}")
    print(f"Is SDK error: {isinstance(e, exc.GraphOLAPError)}")

4

HTTP Status Mapping

How API responses become exceptions

exception_from_response(status_code, error_code, message, details=None) -> GraphOLAPError

The SDK uses this factory function internally to convert HTTP error responses into the appropriate exception class. You normally don’t call it directly, but it is useful for understanding the mapping.

HTTP Status	Default Exception	Refinements via error_code
401	AuthenticationError	—
403	ForbiddenError	—
404	NotFoundError	—
409	ConflictError	RESOURCE_LOCKED, DEPENDENCY_EXISTS, INVALID_STATE
422	ValidationError	VALIDATION_FAILED
429	ConcurrencyLimitError	CONCURRENCY_LIMIT
500	ServerError	RYUGRAPH_ERROR, ALGORITHM_FAILED, SNAPSHOT_FAILED, INSTANCE_FAILED
503	ServiceUnavailableError	—

When an error_code is present, it takes precedence over the HTTP status.

# Factory function in action
e1 = exc.exception_from_response(404, None, "Mapping 42 not found")
print(f"404 -> {type(e1).__name__}: {e1}")

e2 = exc.exception_from_response(409, "RESOURCE_LOCKED", "Instance locked",
                                  {"holder_name": "[email protected]", "algorithm": "PageRank"})
print(f"409 RESOURCE_LOCKED -> {type(e2).__name__}: {e2}")
print(f"  holder: {e2.holder_name}, algorithm: {e2.algorithm}")

e3 = exc.exception_from_response(429, "CONCURRENCY_LIMIT", "Limit exceeded",
                                  {"limit_type": "user", "current_count": 5, "max_allowed": 5})
print(f"429 CONCURRENCY_LIMIT -> {type(e3).__name__}: {e3}")
print(f"  {e3.current_count}/{e3.max_allowed} ({e3.limit_type})")

5

Best Practices

Guidelines for robust error handling

1. Catch specific exceptions before general ones. Python matches the first except clause, so place narrow types (NotFoundError) before broad ones (GraphOLAPError).

2. Use GraphOLAPError as a catch-all. It covers every SDK exception, making it ideal for logging or generic fallback handlers.

3. Inspect .details for programmatic decisions. The dict often contains structured data (field names, limits, lock holders) that you can act on without parsing the message string.

4. Let ConflictError subtypes guide retry logic.

   • ResourceLockedError — wait for the lock to release, then retry.
   • ConcurrencyLimitError — terminate an idle instance before creating a new one.
   • InvalidStateError — the resource is in the wrong lifecycle state; check status.

5. Handle TimeoutError separately from server errors. Timeouts usually mean the operation is still running server-side; retrying immediately may cause duplicates.

# Recommended pattern: specific-to-general
def safe_get_instance(instance_id: int):
    try:
        return client.instances.get(instance_id)
    except exc.NotFoundError:
        print(f"Instance {instance_id} does not exist")
        return None
    except exc.AuthenticationError:
        print("Session expired -- re-authenticate")
        raise
    except exc.GraphOLAPError as e:
        print(f"Unexpected SDK error: {e}")
        raise

result = safe_get_instance(999999)
print(f"Result: {result}")

Key Takeaways

• All SDK exceptions inherit from GraphOLAPError -- use it as a catch-all
• NotFoundError, ValidationError, and ConflictError are the most common in day-to-day use
• Access .details for structured error context beyond the message string
• exception_from_response() maps HTTP status codes and API error codes to exception classes
• Catch specific exceptions before GraphOLAPError to handle different failures appropriately