Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openmem.blog/llms.txt

Use this file to discover all available pages before exploring further.

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 classerror.codeerror.typeWhen raised
UnauthorizedErrorunauthorizedauthMissing or invalid credentials
ScopeDeniedErrorscope_deniedauthApp lacks the required scope permission
NotFoundErrornot_foundnot_foundMemory ID does not exist
InvalidRequestErrorinvalid_requestinvalidMalformed or missing request parameters
RateLimitedErrorrate_limitedrate_limitedProvider rate limit exceeded
UnsupportedCapabilityErrorunsupported_capabilityinvalidVerb not supported by this provider
ProviderErrorprovider_errorprovider_errorBackend-specific error
UnsupportedProviderErrorinvalid_requestinvalidUnknown 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