Error handling in the openmem SDK

The OMP Python SDK raises typed exceptions so you can write consistent error-handling logic regardless of which provider is underneath. All exceptions inherit from OMPError, carry a standard code, type, provider, and request_id, and mirror the error envelope that the OMP HTTP API returns on failure.

Import

from openmem import (
    OMPError,
    UnauthorizedError,
    ScopeDeniedError,
    NotFoundError,
    InvalidRequestError,
    RateLimitedError,
    UnsupportedCapabilityError,
    ProviderError,
    UnsupportedProviderError,
)

Error hierarchy

All exceptions extend OMPError(Exception). Each subclass maps to a specific error.code value in the OMP wire format.

Exception class	`error.code`	`error.type`	When raised
`UnauthorizedError`	`unauthorized`	`auth`	Missing or invalid credentials
`ScopeDeniedError`	`scope_denied`	`auth`	App lacks the required scope permission
`NotFoundError`	`not_found`	`not_found`	Memory ID does not exist
`InvalidRequestError`	`invalid_request`	`invalid`	Malformed or missing request parameters
`RateLimitedError`	`rate_limited`	`rate_limited`	Provider rate limit exceeded
`UnsupportedCapabilityError`	`unsupported_capability`	`invalid`	Verb not supported by this provider
`ProviderError`	`provider_error`	`provider_error`	Backend-specific error
`UnsupportedProviderError`	`invalid_request`	`invalid`	Unknown provider string passed to `Memory()`

All instances expose the following attributes:

e.message — human-readable description
e.code — machine-readable error code string
e.type — error category (auth, not_found, invalid, rate_limited, provider_error)
e.provider — the provider that raised the error, or None
e.request_id — the provider-assigned request ID for tracing, or None

Common error handling pattern

from openmem import Memory, OMPError, NotFoundError, RateLimitedError
import time

mem = Memory(provider="postgres", url="postgresql://localhost/omp")

try:
    record = mem.get("mem_does_not_exist")
except NotFoundError:
    print("Memory not found")
except RateLimitedError:
    time.sleep(1)
    # retry
except OMPError as e:
    print(f"OMP error {e.code}: {e.message}")
    print(f"Provider: {e.provider}, Request ID: {e.request_id}")

Catching OMPError as the final handler gives you a safe fallback for any OMP-originated exception.

Handling auth errors

from openmem import Memory, UnauthorizedError, ScopeDeniedError

mem = Memory(provider="mem0", api_key="...")

try:
    results = mem.search("health records", user_id="u1", scope="health/*")
except UnauthorizedError:
    print("Invalid or missing API key — check your credentials")
except ScopeDeniedError as e:
    print(f"Permission denied: {e.message}")
    # Prompt the user to grant access to the required scope

Handling unsupported capabilities

Not all providers support every OMP verb. You can either check capabilities upfront or catch UnsupportedCapabilityError at call time:

from openmem import Memory, UnsupportedCapabilityError

mem = Memory(provider="mem0", api_key="...")

# Option A: check upfront
caps = mem.capabilities()
if caps.features.supports_audit:
    entries = mem.audit(user_id="u1")

# Option B: catch at call time
try:
    entries = mem.audit(user_id="u1")
except UnsupportedCapabilityError:
    entries = []

Error envelope structure

When an OMP-native HTTP server returns an error, it uses this JSON envelope. The SDK parses this envelope and raises the matching exception class automatically.

{
  "error": {
    "code": "not_found",
    "message": "Memory mem_abc123 not found",
    "type": "not_found",
    "provider": "postgres",
    "request_id": "req_xyz"
  }
}

You can reconstruct any OMPError subclass from a raw error dict using OMPError.from_response_dict():

raw = {
    "error": {
        "code": "not_found",
        "message": "Memory mem_abc123 not found",
        "type": "not_found",
        "provider": "postgres",
        "request_id": "req_xyz",
    }
}
exc = OMPError.from_response_dict(raw)
# exc is a NotFoundError instance

Provider consistency guarantee

OMP guarantees that the same logical condition raises the same exception class regardless of which provider is active. For example, requesting a non-existent memory ID always raises NotFoundError — whether you’re using the postgres adapter, the mem0 adapter, or a native passthrough provider. You never need to write provider-specific error handling.

Ingestion timeout

ProviderError with code="ingestion_timeout" is a special case raised by async-ingestion providers (mem0, supermemory) when a memory fails to become searchable within the polling timeout. This is distinct from a generic backend failure.

from openmem import Memory, ProviderError

mem = Memory(provider="mem0", api_key="...")
record = mem.add(content="prefers dark mode", user_id="u1")

try:
    mem.wait_for_ingest([record.id], user_id="u1", timeout=10.0)
except ProviderError as e:
    if e.code == "ingestion_timeout":
        print("Memory was stored but not yet indexed — retry search later")
    else:
        raise

Get Started

Core Concepts

Guides

SDK Reference

Import

Error hierarchy

Common error handling pattern

Handling auth errors

Handling unsupported capabilities

Error envelope structure

Provider consistency guarantee

Ingestion timeout

​Import

​Error hierarchy

​Common error handling pattern

​Handling auth errors

​Handling unsupported capabilities

​Error envelope structure

​Provider consistency guarantee

​Ingestion timeout

Import

Error hierarchy

Common error handling pattern

Handling auth errors

Handling unsupported capabilities

Error envelope structure

Provider consistency guarantee

Ingestion timeout