Error Handling

All SDK calls throw/raise instances of a single exception tree. Catching the right one lets you distinguish "need to reconnect" from "upgrade your plan" from "bad credentials".

Both SDKs expose the same fine-grained hierarchy mapped from the API's error_code. Python uses bare class names (AuthorizationError); Node prefixes everything with Memsy (MemsyAuthorizationError).

The hierarchy

MemsyError
├── MemsyConnectionError        # network error or timeout
└── MemsyAPIError               # non-2xx HTTP response
    ├── AuthenticationError     # 401 — invalid or missing API key
    ├── AuthorizationError      # 403 — key lacks the required scope
    ├── FeatureNotAvailable     # 403 — feature not on your tier
    ├── OrgIdNotAllowedError    # 400 — free-tier: org_id not allowed in request
    ├── SeatRequiredError       # 403 — endpoint requires an assigned seat
    ├── OrgLimitReachedError    # 403 — org tier limit reached
    ├── KeyLimitReachedError    # 403 — API key tier limit reached
    ├── BillingNotEnabledError  # 403 — billing not enabled for this org
    ├── SeatLimitReachedError   # 409 — purchased seat limit reached
    ├── RateLimitExceeded       # 429 — rate limit hit (after retries)
    └── UsageLimitExceeded      # 429 — plan quota exceeded

MemsyError
├── MemsyConnectionError              # network error or timeout
└── MemsyAPIError                     # non-2xx HTTP response
    ├── MemsyAuthError                # 401 — invalid or missing API key
    ├── MemsyAuthorizationError       # 403 — key lacks the required scope
    ├── MemsyFeatureNotAvailableError # 403 — feature not on your tier
    ├── MemsyOrgIdNotAllowedError     # 400 — free-tier: org_id not allowed in request
    ├── MemsySeatRequiredError        # 403 — endpoint requires an assigned seat
    ├── MemsyOrgLimitReachedError     # 403 — org tier limit reached
    ├── MemsyKeyLimitReachedError     # 403 — API key tier limit reached
    ├── MemsyBillingNotEnabledError   # 403 — billing not enabled for this org
    ├── MemsySeatLimitReachedError    # 409 — purchased seat limit reached
    ├── MemsyRateLimitError           # 429 — rate limit hit (after retries)
    └── MemsyUsageLimitExceededError  # 429 — plan quota exceeded

No exception classes — read the HTTP status code directly from the response.

200/204    success
400        request validation failed
401        invalid or missing API key
403        permission denied (feature/billing/seat/scope — read response body for details)
409        seat limit reached
429        rate-limited (Retry-After header may be set) or plan quota exhausted
5xx        server-side error

A full example

Imports come from memsy.exceptions:

from memsy import MemsyClient
from memsy.exceptions import (
    AuthenticationError,
    AuthorizationError,
    FeatureNotAvailable,
    RateLimitExceeded,
    UsageLimitExceeded,
    MemsyConnectionError,
    MemsyAPIError,
)

client = MemsyClient(base_url="...", api_key="***")

try:
    results = client.search("preferences")
except AuthenticationError:
    refresh_api_key()
except AuthorizationError as e:
    print(f"Missing required scope: {e.required_scope}")
except FeatureNotAvailable as e:
    print(f"Feature '{e.feature}' requires an upgrade from {e.current_tier}")
    print(f"Upgrade at: {e.upgrade_url}")
except RateLimitExceeded as e:
    print(f"Rate limited; retry after {e.retry_after}s")
except UsageLimitExceeded as e:
    print(f"Hit {e.dimension} limit ({e.current}/{e.limit})")
    print(f"Upgrade at: {e.upgrade_url}")
except MemsyConnectionError:
    ...
except MemsyAPIError as e:
    print(f"API error {e.status_code}: {e.detail}")

import {
  MemsyClient,
  MemsyAuthError,
  MemsyAuthorizationError,
  MemsyFeatureNotAvailableError,
  MemsyRateLimitError,
  MemsyUsageLimitExceededError,
  MemsyConnectionError,
  MemsyAPIError,
} from '@memsy-io/memsy';

const client = new MemsyClient({ baseUrl: '...', apiKey: '***' });

try {
  const results = await client.search('preferences');
} catch (err) {
  if (err instanceof MemsyAuthError) {
    await refreshApiKey();
  } else if (err instanceof MemsyAuthorizationError) {
    console.log(`Missing required scope: ${err.requiredScope}`);
  } else if (err instanceof MemsyFeatureNotAvailableError) {
    console.log(`Feature '${err.feature}' requires upgrade from ${err.currentTier}`);
  } else if (err instanceof MemsyRateLimitError) {
    console.log(`Rate limited; retry after ${err.retryAfter ?? 'unknown'}s`);
  } else if (err instanceof MemsyUsageLimitExceededError) {
    console.log(`Hit ${err.dimension} limit (${err.current}/${err.limit})`);
  } else if (err instanceof MemsyConnectionError) {
    // network / timeout — retry with backoff
  } else if (err instanceof MemsyAPIError) {
    console.log(`API error ${err.statusCode}: ${err.detail}`);
  } else {
    throw err;
  }
}

response=$(curl -s -w "\n%{http_code}" -X POST "$MEMSY_BASE_URL/search" \
  -H "Authorization: Bearer $MEMSY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "preferences"}')

body=$(echo "$response" | head -n -1)
status=$(echo "$response" | tail -n 1)

case "$status" in
  200) echo "$body" ;;
  401) echo "Auth failed — refresh API key" ;;
  403) echo "Permission denied: $body" ;;
  429) echo "Rate limited or quota exhausted: $body" ;;
  5*)  echo "Server error $status — retry later" ;;
  *)   echo "Unexpected $status: $body" ;;
esac

Control-plane errors (Python only)

MemsyControlClient is currently Python-only. When using it, you may also encounter:

from memsy.exceptions import (
    OrgLimitReachedError,
    KeyLimitReachedError,
    BillingNotEnabledError,
    SeatRequiredError,
    SeatLimitReachedError,
)

try:
    key = control.keys.create("my-key", scopes=["read", "write"])
except KeyLimitReachedError as e:
    print(f"Key limit reached: {e.current}/{e.limit}")
except BillingNotEnabledError as e:
    print(f"Billing not enabled. Express interest at: {e.interest_path}")

Exception-specific attributes (Python)

`AuthorizationError`

Attribute	Description
`required_scope`	Scope your API key is missing, if known.

`FeatureNotAvailable`

Attribute	Description
`feature`	The gated feature's identifier.
`current_tier`	The tier of the API key that tried to use it.
`upgrade_url`	Deep-link to the dashboard billing page.

`OrgLimitReachedError` / `KeyLimitReachedError`

Attribute	Description
`limit`	Tier limit (orgs or keys).
`current`	Current count.

`BillingNotEnabledError`

Attribute	Description
`interest_path`	API path to express Pro plan interest.

`SeatLimitReachedError`

Attribute	Description
`purchased_seats`	Total purchased seats.
`assigned_seats`	Currently assigned seats.
`pending_invites`	Pending invite count.

`RateLimitExceeded`

Attribute	Description
`retry_after`	Seconds to wait before retrying, parsed from `Retry-After`.

`UsageLimitExceeded`

Attribute	Description
`dimension`	What quota was exhausted (e.g. `"events_ingested"`).
`current`	Current usage count.
`limit`	The limit that was exceeded.
`upgrade_url`	Deep-link to upgrade.

`MemsyAPIError` (base class)

Every API-side error carries:

Attribute	Description
`status_code`	HTTP status.
`detail`	Server-provided message.
`error_code`	Stable machine-readable code, e.g. `"feature_not_available"`.
`response`	The raw `httpx.Response` for deeper inspection.

Catch broadly or narrowly?

In request handlers / agent loops — catch MemsyError and surface a friendly error. Log the specific subclass for debugging.
In pipelines with budgets — handle UsageLimitExceeded and FeatureNotAvailable distinctly so you can route to an alert channel and link the upgrade page.
In retryable background jobs — catch MemsyConnectionError and RateLimitExceeded separately from API-level errors; they're the only ones that "just work" on a later retry.
In control-plane admin code — handle BillingNotEnabledError and SeatLimitReachedError and link users to the appropriate dashboard flow.

How automatic 429 retry behaves before these exceptions fire → Retries.