SDKs · Python

Python Types & Errors

Use public dataclasses, typed dictionaries, and six exception classes to make success and failure paths explicit. Keep retry behavior narrow and operation-aware.

Public result families

Family	Examples	How to consume it
Memory dataclasses	`Memory`, `QueryResponse`, `BulkAddResponse`, `ComposeResponse`, `Relation`	Use attributes with snake_case names.
Add union	`Memory \| AddSkippedResponse`	Use `isinstance` before reading created-memory fields.
Control-plane dictionaries	`LoginResponse`, `Project`, `ExportJob`, `Webhook`, `WebhookDelivery`	Use documented snake_case keys and tolerate optional fields.
Delete result	`list[int]`	Compare confirmed IDs with requested IDs.

Error classes

Class	Typical condition	Default action
`AuthError`	401 or 403	Fix authentication, permission, or scope.
`ValidationError`	400, 409, 422, or client validation	Correct the request; do not retry unchanged.
`NotFoundError`	404	Show an unavailable state without revealing other scopes.
`RateLimitError`	429	Use `retry_after_seconds` and bound attempts.
`ServerError`	5xx	Retry safe reads with bounded backoff; reconcile writes.
`MemorySyncError`	Network, timeout, or other SDK failure	Treat mutation outcomes as uncertain.

Catch specific errors first

handle_errors.py

from memorysync import (
    AuthError,
    MemorySyncError,
    NotFoundError,
    RateLimitError,
    ServerError,
    ValidationError,
)

try:
    memory = client.get(101)
except NotFoundError:
    memory = None
except (AuthError, ValidationError):
    raise
except RateLimitError as error:
    print("Retry after", error.retry_after_seconds)
    raise
except ServerError:
    raise
except MemorySyncError:
    raise

Retry reads narrowly

retry_read.py

import random
import time
from memorysync import RateLimitError, ServerError

def query_with_retry(client, question: str, attempts: int = 3):
    for attempt in range(attempts):
        try:
            return client.query(question, k=5)
        except RateLimitError as error:
            if attempt == attempts - 1:
                raise
            time.sleep(error.retry_after_seconds or 1.0)
        except ServerError:
            if attempt == attempts - 1:
                raise
            time.sleep((2 ** attempt) * 0.25 + random.random() * 0.1)

    raise RuntimeError("unreachable")

Use error context defensively

Attribute	Type	Availability
`status_code`	`int \| None`	Present when an HTTP response supplied a status.
`response`	`Any`	Parsed response body when one was available.
`request_id`	`str \| None`	Present only when the server returned a request identifier.
`retry_after_seconds`	`float`	Available on `RateLimitError`.

Log a safe support record

logging.py

import logging
from memorysync import MemorySyncError

log = logging.getLogger(__name__)

try:
    response = client.query("What preference applies?", k=5)
except MemorySyncError as error:
    log.warning(
        "memory query failed",
        extra={
            "status_code": error.status_code,
            "request_id": error.request_id,
        },
    )
    raise

Related contracts

Rate Limits & Errors

Review shared status and recovery guidance.

Python Memory Client

See operation-specific success types.

Python Control Plane

Use typed dictionaries for administrative results.

Production Patterns

Apply uncertain-write and observability rules.

Was this page helpful?

← Previous

Async Usage

Control Plane