Error Handling

Overview

The Synap SDK uses a structured error hierarchy to distinguish between transient errors (which are automatically retried) and permanent errors (which require your intervention). Understanding this hierarchy is essential for building robust integrations. This page is the handling guide: the hierarchy, when each error fires, and the try/except patterns to catch them.

Full error reference →

For the exhaustive catalog of server-side error codes (the wire-level code field, HTTP status, and details shape) see Error Codes. For the complete SDK exception table at a glance, see SDK Reference: Error handling.

Error Hierarchy

All Synap errors inherit from SynapError. The two main branches determine retry behavior:

SynapError (base)
├── SynapTransientError (retryable: SDK auto-retries)
│   ├── NetworkTimeoutError
│   ├── RateLimitError
│   ├── ServiceUnavailableError
│   └── AgentUnavailableError
└── SynapPermanentError (non-retryable: requires code/config fix)
    ├── InvalidInputError
    │   ├── InvalidInstanceIdError
    │   └── InvalidConversationIdError
    ├── AuthenticationError
    ├── ContextNotFoundError
    ├── SessionExpiredError
    ├── InsufficientCreditsError
    ├── ListeningAlreadyActiveError
    └── ListeningNotActiveError

All errors include an optional correlation_id field that uniquely identifies the request. This ID is invaluable for debugging and when contacting Synap support.

The hierarchy below reflects the full public error surface. AgentUnavailableError is transient (retryable); all others under SynapPermanentError are non-retryable.

Transient Errors

Transient errors represent temporary conditions that typically resolve on their own. The SDK automatically retries these errors according to your configured retry policy. You only need to handle them if all retry attempts are exhausted.

NetworkTimeoutError

SynapTransientError

Raised when a network request to Synap Cloud times out before completing.

When it occurs:

Network connectivity issues between your application and Synap Cloud
DNS resolution failures
The request exceeded the configured connect or read timeout

How to handle:

conversation_id must be a valid UUID string; non-UUID values are rejected by the server. Generate one with str(uuid.uuid4()), or reuse the UUID you already manage per conversation. The examples below use str(uuid.uuid4()) to make this explicit.

import uuid
from maximem_synap import NetworkTimeoutError

try:
    context = await sdk.conversation.context.fetch(
        conversation_id=str(uuid.uuid4()),
        mode="fast"
    )
except NetworkTimeoutError as e:
    logger.warning(
        "Network timeout after all retries (correlation_id=%s)",
        e.correlation_id
    )
    # Fall back to cached context or proceed without memory
    context = None

import { randomUUID } from 'node:crypto';
import { NetworkTimeoutError, isSynapError } from '@maximem/synap-js-sdk';

try {
  let context = await sdk.conversation.context.fetch({
    conversation_id: randomUUID(),
    mode: 'fast',
  });
} catch (e) {
  if (!(e instanceof NetworkTimeoutError)) throw e;
  console.warn('Network timeout after all retries (correlation_id=%s)', e.correlationId);
    // Fall back to cached context or proceed without memory
  context = null;
}

import { randomUUID } from 'node:crypto';
import { NetworkTimeoutError, isSynapError } from '@maximem/synap-js-sdk';

try {
  let context = await sdk.conversation.context.fetch({
    conversation_id: randomUUID(),
    mode: 'fast',
  });
} catch (e) {
  if (!(e instanceof NetworkTimeoutError)) throw e;
  console.warn('Network timeout after all retries (correlation_id=%s)', e.correlationId);
    // Fall back to cached context or proceed without memory
  context = null;
}

RateLimitError

SynapTransientError

Raised when your application exceeds the rate limit for the Synap API. Includes a retry_after_seconds field indicating how long to wait before retrying.

When it occurs:

Too many requests in a short time window
Burst traffic exceeding your plan’s rate limit

How to handle:

from maximem_synap import RateLimitError

try:
    response = await sdk.memories.create(
        document=doc,
        document_type="ai-chat-conversation",
        user_id=uid,
        customer_id=cid,
    )
except RateLimitError as e:
    logger.warning(
        "Rate limited. Retry after %d seconds (correlation_id=%s)",
        e.retry_after_seconds,
        e.correlation_id
    )
    # The SDK retries automatically, but if all retries are exhausted:
    # - Queue the operation for later
    # - Reduce request frequency
    # - Consider upgrading your plan

import { RateLimitError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const response = await sdk.memories.create({
    document: doc,
    document_type: 'ai-chat-conversation',
    user_id: uid,
    customer_id: cid,
  });
} catch (e) {
  if (!(e instanceof RateLimitError)) throw e;
  console.warn('Rate limited. Retry after %d seconds (correlation_id=%s)', e.retryAfterSeconds, e.correlationId);
    // The SDK retries automatically, but if all retries are exhausted:
    // - Queue the operation for later
    // - Reduce request frequency
    // - Consider upgrading your plan
}

import { RateLimitError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const response = await sdk.memories.create({
    document: doc,
    document_type: 'ai-chat-conversation',
    user_id: uid,
    customer_id: cid,
  });
} catch (e) {
  if (!(e instanceof RateLimitError)) throw e;
  console.warn('Rate limited. Retry after %d seconds (correlation_id=%s)', e.retryAfterSeconds, e.correlationId);
    // The SDK retries automatically, but if all retries are exhausted:
    // - Queue the operation for later
    // - Reduce request frequency
    // - Consider upgrading your plan
}

The SDK’s built-in retry policy respects retry_after_seconds automatically. If the rate limit is short (a few seconds), the SDK waits and retries without raising the error to your code. The error only surfaces when all retry attempts are exhausted.

ServiceUnavailableError

SynapTransientError

Raised when Synap Cloud is temporarily unavailable due to maintenance, deployment, or an outage.

When it occurs:

Synap Cloud is undergoing maintenance
A rolling deployment is in progress
Temporary backend issues

How to handle:

import uuid
from maximem_synap import ServiceUnavailableError

try:
    context = await sdk.conversation.context.fetch(
        conversation_id=str(uuid.uuid4()),
        mode="fast"
    )
except ServiceUnavailableError as e:
    logger.error(
        "Synap Cloud unavailable (correlation_id=%s)",
        e.correlation_id
    )
    # Serve from cache if available, or degrade gracefully

import { randomUUID } from 'node:crypto';
import { ServiceUnavailableError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const context = await sdk.conversation.context.fetch({
    conversation_id: randomUUID(),
    mode: 'fast',
  });
} catch (e) {
  if (!(e instanceof ServiceUnavailableError)) throw e;
  console.error('Synap Cloud unavailable (correlation_id=%s)', e.correlationId);
    // Serve from cache if available, or degrade gracefully
}

import { randomUUID } from 'node:crypto';
import { ServiceUnavailableError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const context = await sdk.conversation.context.fetch({
    conversation_id: randomUUID(),
    mode: 'fast',
  });
} catch (e) {
  if (!(e instanceof ServiceUnavailableError)) throw e;
  console.error('Synap Cloud unavailable (correlation_id=%s)', e.correlationId);
    // Serve from cache if available, or degrade gracefully
}

Permanent Errors

Permanent errors indicate problems that will not resolve by retrying. They require changes to your code, configuration, or data.

InvalidInputError

SynapPermanentError

Raised when the request contains invalid parameters or data that fails validation.

When it occurs:

Invalid document_type value
Missing required fields
Parameter values outside valid ranges
Malformed data in the request body

How to handle:

from maximem_synap import InvalidInputError

try:
    response = await sdk.memories.create(
        document="",                       # Empty document
        document_type="invalid-type",      # Invalid document_type value
        user_id="user_123",
        customer_id="acme_corp",
    )
except InvalidInputError as e:
    logger.error("Invalid input: %s", e)
    # Fix the input data and retry

import { InvalidInputError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const response = await sdk.memories.create({
    document: '',  // Empty document
    document_type: 'invalid-type',
    // Invalid document_type value
    user_id: 'user_123',
    customer_id: 'acme_corp',
  });
} catch (e) {
  if (!(e instanceof InvalidInputError)) throw e;
  console.error('Invalid input: %s', e);
    // Fix the input data and retry
}

import { InvalidInputError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const response = await sdk.memories.create({
    document: '',  // Empty document
    document_type: 'invalid-type',
    // Invalid document_type value
    user_id: 'user_123',
    customer_id: 'acme_corp',
  });
} catch (e) {
  if (!(e instanceof InvalidInputError)) throw e;
  console.error('Invalid input: %s', e);
    // Fix the input data and retry
}

InvalidInstanceIdError

InvalidInputError

A defined subtype of InvalidInputError for an unknown or malformed instance_id.

A malformed instance_id is rejected by the SDK itself, and raised from the constructor before any request is made: you do not reach initialize(). An id that is well-formed but unknown to the server is a different case: it comes back as an HTTP 400 and surfaces as the base InvalidInputError. Catching InvalidInputError handles both, since this is a subtype of it.

When it occurs:

The instance_id does not match the expected format: inst_ followed by 16 hex characters, e.g. inst_a1b2c3d4e5f67890. Raised by MaximemSynapSDK(...) itself; an empty value is left alone, since the instance is normally resolved from the API key during initialize().
The instance has been deleted or deactivated (server-side, surfaces as InvalidInputError)
A typo in the instance ID

How to handle:

from maximem_synap import InvalidInputError

try:
    sdk = MaximemSynapSDK(instance_id=configured_id, api_key=key)
    await sdk.initialize()
except InvalidInputError as e:   # also catches InvalidInstanceIdError
    logger.error(
        "Invalid instance ID. Verify in the Synap Dashboard. "
        "(correlation_id=%s)", getattr(e, "correlation_id", None)
    )
    raise

import { SynapClient, InvalidInputError } from '@maximem/synap-js-sdk';

try {
  const sdk = new SynapClient({ instanceId: configuredId, apiKey: key });
  await sdk.initialize();
} catch (e) {
  // Also catches InvalidInstanceIdError, which extends InvalidInputError.
  if (!(e instanceof InvalidInputError)) throw e;
  console.error(
    'Invalid instance ID. Verify in the Synap Dashboard. (correlation_id=%s)',
    e.correlationId,
  );
  throw e;
}

import { SynapClient, InvalidInputError } from '@maximem/synap-js-sdk';

try {
  const sdk = new SynapClient({ instanceId: configuredId, apiKey: key });
  await sdk.initialize();
} catch (e) {
  // Also catches InvalidInstanceIdError, which extends InvalidInputError.
  if (!(e instanceof InvalidInputError)) throw e;
  console.error(
    'Invalid instance ID. Verify in the Synap Dashboard. (correlation_id=%s)',
    e.correlationId,
  );
  throw e;
}

Passing instance_id is optional, and usually unnecessary: the API key already identifies its instance and the SDK resolves it during initialize(). Omitting it avoids this error class entirely.

InvalidConversationIdError

InvalidInputError

A defined subtype of InvalidInputError for a malformed conversation_id (for example, a non-UUID string).

The SDK currently surfaces a malformed conversation_id as the base InvalidInputError (HTTP 400), not as this specific subtype. Catch InvalidInputError. Note that a well-formed conversation_id with no messages yet does not raise; it returns an empty ContextResponse (see cold-start behavior).

When it occurs:

The conversation_id is not a valid UUID
A typo or wrong identifier format

How to handle:

import uuid
from maximem_synap import InvalidInputError

try:
    context = await sdk.conversation.context.fetch(
        conversation_id=str(uuid.uuid4())  # must be a valid UUID
    )
except InvalidInputError as e:
    logger.warning("Malformed conversation_id: %s", e)
    # Generate a valid UUID and retry

import { randomUUID } from 'node:crypto';
import { InvalidInputError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const context = await sdk.conversation.context.fetch({
    conversation_id: randomUUID(),  // must be a valid UUID
  });
} catch (e) {
  if (!(e instanceof InvalidInputError)) throw e;
  console.warn('Malformed conversation_id: %s', e);
    // Generate a valid UUID and retry
}

import { randomUUID } from 'node:crypto';
import { InvalidInputError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const context = await sdk.conversation.context.fetch({
    conversation_id: randomUUID(),  // must be a valid UUID
  });
} catch (e) {
  if (!(e instanceof InvalidInputError)) throw e;
  console.warn('Malformed conversation_id: %s', e);
    // Generate a valid UUID and retry
}

AuthenticationError

SynapPermanentError

Raised when the SDK cannot authenticate with Synap Cloud. This is a general authentication failure.

When it occurs:

API key is invalid or revoked
No API key was provided (neither SYNAP_API_KEY env var nor the api_key= constructor argument)
The instance’s credentials have been rotated without updating the API key your application uses

How to handle:

from maximem_synap import AuthenticationError

try:
    await sdk.initialize()
except AuthenticationError as e:
    logger.error(
        "Authentication failed: %s (correlation_id=%s)",
        e, e.correlation_id
    )
    # Re-bootstrap with a new token, or check SYNAP_API_KEY in the environment

import { AuthenticationError, isSynapError } from '@maximem/synap-js-sdk';

try {
  await sdk.initialize();
} catch (e) {
  if (!(e instanceof AuthenticationError)) throw e;
  console.error('Authentication failed: %s (correlation_id=%s)', e, e.correlationId);
    // Re-bootstrap with a new token, or check SYNAP_API_KEY in the environment
}

import { AuthenticationError, isSynapError } from '@maximem/synap-js-sdk';

try {
  await sdk.initialize();
} catch (e) {
  if (!(e instanceof AuthenticationError)) throw e;
  console.error('Authentication failed: %s (correlation_id=%s)', e, e.correlationId);
    // Re-bootstrap with a new token, or check SYNAP_API_KEY in the environment
}

ContextNotFoundError

SynapPermanentError

Raised when a requested context resource genuinely cannot be located, distinct from a valid resource that simply has no memories yet, which returns an empty ContextResponse rather than raising.

Empty result vs. raised error, which happens per method:

sdk.conversation.context.fetch(): a brand-new or never-ingested conversation_id returns an empty ContextResponse (facts == [], preferences == [], etc.), not an error. This is the normal cold-start path. A malformed (non-UUID) conversation_id raises InvalidInputError instead.
sdk.user.context.fetch() / sdk.customer.context.fetch() / sdk.client.context.fetch(): a scope that has never had memories ingested also returns an empty ContextResponse. Treat empty lists as “no context yet,” not as an error.

ContextNotFoundError is reserved for the case where the underlying context resource itself is missing or was removed, not for the everyday “new conversation / new user” case. When it occurs:

A previously available context resource was deleted before retrieval
The backend cannot locate the addressed context resource (as opposed to locating it and finding it empty)

How to handle:

from maximem_synap import ContextNotFoundError

try:
    context = await sdk.user.context.fetch(user_id="user_12345")
except ContextNotFoundError:
    logger.info("Context resource missing for user, starting with empty state")
    context = None

# Note: a user who simply has no memories yet does NOT raise here; the fetch
# returns an empty ContextResponse. Check `not context.facts and not
# context.preferences and ...` for the cold-start case rather than relying on
# this exception.

import { ContextNotFoundError } from '@maximem/synap-js-sdk';

let context = null;
try {
  context = await sdk.user.context.fetch({ user_id: 'user_12345' });
} catch (e) {
  if (!(e instanceof ContextNotFoundError)) throw e;
  console.info('Context resource missing for user, starting with empty state');
  context = null;
}

// Note: a user who simply has no memories yet does NOT raise here; the fetch
// returns an empty response, and each collection may be absent entirely.
// Check `!(context?.facts?.length) && !(context?.preferences?.length)` for the
// cold-start case rather than relying on this exception.

import { ContextNotFoundError, type RawContext } from '@maximem/synap-js-sdk';

let context: RawContext | null = null;
try {
  context = await sdk.user.context.fetch({ user_id: 'user_12345' });
} catch (e) {
  if (!(e instanceof ContextNotFoundError)) throw e;
  console.info('Context resource missing for user, starting with empty state');
  context = null;
}

// Note: a user who simply has no memories yet does NOT raise here; the fetch
// returns an empty response, and each collection may be absent entirely.
// Check `!(context?.facts?.length) && !(context?.preferences?.length)` for the
// cold-start case rather than relying on this exception.

SessionExpiredError

SynapPermanentError

Raised when the current session has expired and cannot be resumed. Sessions are time-bounded and must be re-established after expiry.

When it occurs:

The session has been idle beyond its expiry window
The session was invalidated server-side (e.g., credential rotation)

How to handle:

import uuid
from maximem_synap import SessionExpiredError

try:
    context = await sdk.conversation.context.fetch(
        conversation_id=str(uuid.uuid4())
    )
except SessionExpiredError as e:
    logger.warning(
        "Session expired (correlation_id=%s). Re-initializing...",
        e.correlation_id
    )
    await sdk.initialize()
    # Retry the operation

import { randomUUID } from 'node:crypto';
import { SessionExpiredError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const context = await sdk.conversation.context.fetch({
    conversation_id: randomUUID(),
  });
} catch (e) {
  if (!(e instanceof SessionExpiredError)) throw e;
  console.warn('Session expired (correlation_id=%s). Re-initializing...', e.correlationId);
  await sdk.initialize();
    // Retry the operation
}

import { randomUUID } from 'node:crypto';
import { SessionExpiredError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const context = await sdk.conversation.context.fetch({
    conversation_id: randomUUID(),
  });
} catch (e) {
  if (!(e instanceof SessionExpiredError)) throw e;
  console.warn('Session expired (correlation_id=%s). Re-initializing...', e.correlationId);
  await sdk.initialize();
    // Retry the operation
}

InsufficientCreditsError

SynapPermanentError

Raised when the client’s credit balance is too low to satisfy the request. Carries balance_credits, minimum_required_credits, recovery_url, and redeem_url so you can surface the right next-step to the user. See Pricing & Credits for how credits and overage work.

When it occurs:

The client has run out of credits
The current credit balance is below the minimum required for the requested operation

How to handle:

from maximem_synap import InsufficientCreditsError

try:
    response = await sdk.memories.create(
        document=conversation_text,
        document_type="ai-chat-conversation",
        user_id=user_id,
        customer_id=customer_id,
    )
except InsufficientCreditsError as e:
    logger.error(
        "Insufficient credits: balance=%s, required=%s, recover=%s",
        e.balance_credits, e.minimum_required_credits, e.recovery_url
    )
    # Surface the recovery / redeem URL to the operator or user

import { InsufficientCreditsError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const response = await sdk.memories.create({
    document: conversation_text,
    document_type: 'ai-chat-conversation',
    user_id: user_id,
    customer_id: customer_id,
  });
} catch (e) {
  if (!(e instanceof InsufficientCreditsError)) throw e;
  console.error('Insufficient credits: balance=%s, required=%s, recover=%s', e.balanceCredits, e.requiredCredits, e.recoveryUrl);
    // Surface the recovery / redeem URL to the operator or user
}

import { InsufficientCreditsError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const response = await sdk.memories.create({
    document: conversation_text,
    document_type: 'ai-chat-conversation',
    user_id: user_id,
    customer_id: customer_id,
  });
} catch (e) {
  if (!(e instanceof InsufficientCreditsError)) throw e;
  console.error('Insufficient credits: balance=%s, required=%s, recover=%s', e.balanceCredits, e.requiredCredits, e.recoveryUrl);
    // Surface the recovery / redeem URL to the operator or user
}

AgentUnavailableError

SynapTransientError

Raised when the Synap agent backing the instance is temporarily unavailable. This is a transient error; the SDK will automatically retry.

When it occurs:

The agent process is restarting or being redeployed
Temporary resource contention on the backend

How to handle:

from maximem_synap import AgentUnavailableError

try:
    response = await sdk.memories.create(
        document=conversation_text,
        user_id=user_id,
        customer_id=customer_id
    )
except AgentUnavailableError as e:
    logger.warning(
        "Agent unavailable after all retries (correlation_id=%s)",
        e.correlation_id
    )
    # Queue for retry later

import { AgentUnavailableError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const response = await sdk.memories.create({
    document: conversation_text,
    user_id: user_id,
    customer_id: customer_id,
  });
} catch (e) {
  if (!(e instanceof AgentUnavailableError)) throw e;
  console.warn('Agent unavailable after all retries (correlation_id=%s)', e.correlationId);
    // Queue for retry later
}

import { AgentUnavailableError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const response = await sdk.memories.create({
    document: conversation_text,
    user_id: user_id,
    customer_id: customer_id,
  });
} catch (e) {
  if (!(e instanceof AgentUnavailableError)) throw e;
  console.warn('Agent unavailable after all retries (correlation_id=%s)', e.correlationId);
    // Queue for retry later
}

The SDK automatically retries AgentUnavailableError according to your configured retry policy. This error only surfaces to your code when all retry attempts are exhausted.

ListeningAlreadyActiveError

SynapPermanentError

Raised when you call listen() on an instance that already has an active listening stream. Only one stream can be active per SDK instance at a time.

When it occurs:

Calling listen() a second time without first calling stop_listening()
Duplicate initialization paths in your application

How to handle:

from maximem_synap import ListeningAlreadyActiveError

try:
    await sdk.instance.listen(on_context=on_event)
except ListeningAlreadyActiveError:
    logger.warning("Listening stream already active; skipping duplicate call")
    # No action needed; the existing stream is still running

import { ListeningAlreadyActiveError, isSynapError } from '@maximem/synap-js-sdk';

try {
  await sdk.instance.listen({
    on_context: on_event,
  });
} catch (e) {
  if (!(e instanceof ListeningAlreadyActiveError)) throw e;
  console.warn('Listening stream already active; skipping duplicate call');
    // No action needed; the existing stream is still running
}

import { ListeningAlreadyActiveError, isSynapError } from '@maximem/synap-js-sdk';

try {
  await sdk.instance.listen({
    on_context: on_event,
  });
} catch (e) {
  if (!(e instanceof ListeningAlreadyActiveError)) throw e;
  console.warn('Listening stream already active; skipping duplicate call');
    // No action needed; the existing stream is still running
}

ListeningNotActiveError

SynapPermanentError

Raised by send_message() when no listening stream is currently active.

When it occurs:

Calling send_message() before listen() has been called
Calling send_message() after stop_listening(), or while the stream is down and has not yet reconnected

stop_listening() does not raise this. It is idempotent and a safe no-op when no stream is active, so it needs no guard.

How to handle:

from maximem_synap import ListeningNotActiveError

try:
    await sdk.instance.send_message(
        content=text,
        conversation_id=conversation_id,
        user_id=user_id,
        customer_id=customer_id,
    )
except ListeningNotActiveError:
    # Anticipation is an optimization: losing a signal event is not fatal.
    logger.debug("synap_stream_down; skipping anticipation event")

import { ListeningNotActiveError, isSynapError } from '@maximem/synap-js-sdk';

try {
  await sdk.instance.send_message({
    content: text,
    conversation_id: conversation_id,
    user_id: user_id,
    customer_id: customer_id,
  });
} catch (e) {
  if (!(e instanceof ListeningNotActiveError)) throw e;
    // Anticipation is an optimization: losing a signal event is not fatal.
  console.debug('synap_stream_down; skipping anticipation event');
}

import { ListeningNotActiveError, isSynapError } from '@maximem/synap-js-sdk';

try {
  await sdk.instance.send_message({
    content: text,
    conversation_id: conversation_id,
    user_id: user_id,
    customer_id: customer_id,
  });
} catch (e) {
  if (!(e instanceof ListeningNotActiveError)) throw e;
    // Anticipation is an optimization: losing a signal event is not fatal.
  console.debug('synap_stream_down; skipping anticipation event');
}

In a long-lived server, guard with if sdk.instance.is_listening: rather than catching per call. That is what the framework integrations do: stream sends log and never raise.

Stream health

The Listen stream fails in a way that is deliberately invisible to your application, so it needs different handling from the errors above.

Condition	Behaviour
`listen()` fails at startup	Python raises (`AuthenticationError`, `SDKNotInitializedError`). The TypeScript SDK logs a console warning and falls back to HTTP.
Stream drops mid-run	`on_disconnect(reason)` fires; the SDK reconnects with exponential backoff (10 attempts, counter resets on each success).
Server closes at max lifetime (1 hour)	Routine. `on_reconnect(attempt)` fires. Not an error.
Per-instance/client quota exceeded	`RESOURCE_EXHAUSTED`, then a reconnect loop. Usually means one stream per session instead of one per process.
Reconnects exhausted	Stream stays down. `fetch()` keeps working over REST, and no exception ever reaches your code.

A permanently dead stream is silent: retrieval still returns correct results, just slower. Do not infer stream health from your agent working. Export sdk.instance.is_listening to your health endpoint and alert when it stays false. See Real-Time Anticipation in a Server.

Using correlation_id

Every Synap error includes an optional correlation_id that uniquely identifies the failed request within Synap’s distributed tracing system.

import uuid
from maximem_synap import SynapError

try:
    context = await sdk.conversation.context.fetch(
        conversation_id=str(uuid.uuid4())
    )
except SynapError as e:
    logger.error(
        "Synap error: %s | correlation_id: %s | type: %s",
        str(e),
        e.correlation_id,
        type(e).__name__
    )

import { randomUUID } from 'node:crypto';
import { SynapError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const context = await sdk.conversation.context.fetch({
    conversation_id: randomUUID(),
  });
} catch (e) {
  if (!(e instanceof SynapError)) throw e;
  console.error(
    'Synap error: %s | correlation_id: %s | type: %s',
    String(e), e.correlationId, e.constructor.name,
  );
}

import { randomUUID } from 'node:crypto';
import { SynapError, isSynapError } from '@maximem/synap-js-sdk';

try {
  const context = await sdk.conversation.context.fetch({
    conversation_id: randomUUID(),
  });
} catch (e) {
  if (!(e instanceof SynapError)) throw e;
  console.error(
    'Synap error: %s | correlation_id: %s | type: %s',
    String(e), e.correlationId, e.constructor.name,
  );
}

Always log the correlation_id from errors. Synap support can use it to trace the exact request path through the backend, including which pipeline stages were involved, what data was processed, and where the failure occurred.

Retry Policy Configuration

The SDK’s built-in retry policy handles transient errors automatically. You can customize the retry behavior through RetryPolicy in your SDKConfig.

from maximem_synap import SDKConfig, RetryPolicy

config = SDKConfig(
    retry_policy=RetryPolicy(
        max_attempts=5,               # Total attempts (1 initial + 4 retries)
        backoff_base=1.0,             # Base delay in seconds
        backoff_max=10.0,             # Maximum delay between retries
        backoff_jitter=True,          # Add random jitter to prevent thundering herd
        retryable_errors=[            # Error types to retry
            "NetworkTimeoutError",
            "RateLimitError",
            "ServiceUnavailableError",
            "SynapTransientError"
        ]
    )
)

// No SDKConfig wrapper: the policy is an option on the client.
const sdk = new SynapClient({
  retryPolicy: {
    maxAttempts: 5,      // Total attempts (1 initial + 4 retries)
    backoffBase: 1.0,    // Base delay in seconds
    backoffMax: 10.0,    // Maximum delay between retries
    backoffJitter: true, // Add random jitter to prevent thundering herd
  },
});

import { SynapClient, type RetryPolicy } from '@maximem/synap-js-sdk';

const retryPolicy: RetryPolicy = {
  maxAttempts: 5,      // Total attempts (1 initial + 4 retries)
  backoffBase: 1.0,    // Base delay in seconds
  backoffMax: 10.0,    // Maximum delay between retries
  backoffJitter: true, // Add random jitter to prevent thundering herd
};

const sdk = new SynapClient({ retryPolicy });

JavaScript decides this differently, on purpose. There is no retryable_errors list: every transient error is retried, and a non-idempotent call whose outcome is unknown is not, whatever its type. That second rule is what stops a lost response on memories.create from ingesting and billing the same content twice, and a per-error list could switch it off. To handle rate limits yourself, catch RateLimitError at the call site.

Retry Behavior

The SDK uses exponential backoff with optional jitter:

Attempt 1: Immediate
Attempt 2: backoff_base * 2^0 = 1.0s  (± jitter)
Attempt 3: backoff_base * 2^1 = 2.0s  (± jitter)
Attempt 4: backoff_base * 2^2 = 4.0s  (± jitter)
Attempt 5: backoff_base * 2^3 = 8.0s  (± jitter, capped at backoff_max)

For RateLimitError, the SDK respects the retry_after_seconds value instead of the exponential backoff, waiting the exact duration specified by the server.

Disabling Retries

To disable automatic retries entirely (useful for testing or when you implement your own retry logic):

config = SDKConfig(retry_policy=None)

const sdk = new SynapClient({ retryPolicy: null });

const sdk = new SynapClient({ retryPolicy: null });

Customizing Retryable Errors

By default, all four transient error types are retried (NetworkTimeoutError, RateLimitError, ServiceUnavailableError, and AgentUnavailableError). Listing the base SynapTransientError in retryable_errors covers every transient subtype, including any added in future SDK releases. You can customize this list, though adding permanent errors is generally not recommended.

config = SDKConfig(
    retry_policy=RetryPolicy(
        retryable_errors=[
            "NetworkTimeoutError",
            "ServiceUnavailableError"
            # Removed RateLimitError, handle rate limits manually
        ]
    )
)

Python only, deliberately. JavaScript retries every transient error and never a non-idempotent call whose outcome is unknown. Narrowing that by error type could re-enable a retry that ingests and bills the same content twice, so the list is not offered. Catch RateLimitError at the call site instead.

Common Error Handling Patterns

Catch-All with Transient/Permanent Distinction

from maximem_synap import (
    SynapError,
    SynapTransientError,
    SynapPermanentError,
)

try:
    response = await sdk.memories.create(
        document=conversation_text,
        document_type="ai-chat-conversation",
        user_id=user_id,
        customer_id=customer_id,
        mode="long-range",
    )
except SynapTransientError as e:
    # All retries exhausted for a transient error
    logger.warning(
        "Transient error after retries: %s (correlation_id=%s)",
        e, e.correlation_id
    )
    # Queue for retry later, or degrade gracefully
    await retry_queue.enqueue(conversation_text, user_id)

except SynapPermanentError as e:
    # Something is fundamentally wrong
    logger.error(
        "Permanent error: %s (correlation_id=%s)",
        e, e.correlation_id
    )
    # Alert, fix the issue, do not retry as-is
    raise

except SynapError as e:
    # Catch-all for any unexpected Synap error
    logger.error("Unexpected Synap error: %s", e)
    raise

import {
  SynapError,
  TransientError,
  PermanentError,
} from '@maximem/synap-js-sdk';

try {
  const response = await sdk.memories.create({
    document: conversationText,
    document_type: 'ai-chat-conversation',
    user_id: userId,
    customer_id: customerId,
    mode: 'long-range',
  });
} catch (e) {
  // Python has one `except` per class; JavaScript has one `catch`, so the
  // branches move inside it. Order matters the same way: most specific first.
  if (e instanceof TransientError) {
    // All retries exhausted for a transient error
    console.warn(
      'Transient error after retries: %s (correlation_id=%s)',
      e, e.correlationId,
    );
    // Queue for retry later, or degrade gracefully
    await retryQueue.enqueue(conversationText, userId);
  } else if (e instanceof PermanentError) {
    // Something is fundamentally wrong
    console.error('Permanent error: %s (correlation_id=%s)', e, e.correlationId);
    // Alert, fix the issue, do not retry as-is
    throw e;
  } else if (e instanceof SynapError) {
    // Catch-all for any unexpected Synap error
    console.error('Unexpected Synap error: %s', e);
    throw e;
  } else {
    // Not ours: never swallow a bug in your own code as "Synap was down".
    throw e;
  }
}

import {
  SynapError,
  TransientError,
  PermanentError,
} from '@maximem/synap-js-sdk';

try {
  const response = await sdk.memories.create({
    document: conversationText,
    document_type: 'ai-chat-conversation',
    user_id: userId,
    customer_id: customerId,
    mode: 'long-range',
  });
} catch (e) {
  // Python has one `except` per class; JavaScript has one `catch`, so the
  // branches move inside it. Order matters the same way: most specific first.
  if (e instanceof TransientError) {
    // All retries exhausted for a transient error
    console.warn(
      'Transient error after retries: %s (correlation_id=%s)',
      e, e.correlationId,
    );
    // Queue for retry later, or degrade gracefully
    await retryQueue.enqueue(conversationText, userId);
  } else if (e instanceof PermanentError) {
    // Something is fundamentally wrong
    console.error('Permanent error: %s (correlation_id=%s)', e, e.correlationId);
    // Alert, fix the issue, do not retry as-is
    throw e;
  } else if (e instanceof SynapError) {
    // Catch-all for any unexpected Synap error
    console.error('Unexpected Synap error: %s', e);
    throw e;
  } else {
    // Not ours: never swallow a bug in your own code as "Synap was down".
    throw e;
  }
}

Per-Operation Error Handling

from maximem_synap import (
    InvalidInputError,
    NetworkTimeoutError,
    RateLimitError,
    SynapError,
)

async def safe_fetch_context(conversation_id: str, query: str):
    """Fetch context with graceful degradation."""
    try:
        return await sdk.conversation.context.fetch(
            conversation_id=conversation_id,
            search_query=[query],
            mode="fast"
        )

    except InvalidInputError:
        logger.info("Malformed conversation_id %s, skipping memory", conversation_id)
        return None

    except NetworkTimeoutError:
        logger.warning("Timeout fetching context, proceeding without memory")
        return None

    except RateLimitError as e:
        logger.warning(
            "Rate limited, retry after %ds", e.retry_after_seconds
        )
        return None

    except SynapError as e:
        logger.error(
            "Unexpected error fetching context: %s (correlation_id=%s)",
            e, e.correlation_id
        )
        return None

import {
  InvalidInputError,
  NetworkTimeoutError,
  RateLimitError,
  SynapError,
} from '@maximem/synap-js-sdk';

async function safeFetchContext(conversationId, query) {
  // Fetch context with graceful degradation.
  try {
    return await sdk.conversation.context.fetch({
      conversation_id: conversationId,
      search_query: [query],
      mode: 'fast',
    });
  } catch (e) {
    if (e instanceof InvalidInputError) {
      console.info('Malformed conversation_id %s, skipping memory', conversationId);
      return null;
    }
    if (e instanceof NetworkTimeoutError) {
      console.warn('Timeout fetching context, proceeding without memory');
      return null;
    }
    if (e instanceof RateLimitError) {
      console.warn('Rate limited, retry after %ds', e.retryAfterSeconds);
      return null;
    }
    if (e instanceof SynapError) {
      console.error(
        'Unexpected error fetching context: %s (correlation_id=%s)',
        e, e.correlationId,
      );
      return null;
    }
    throw e;   // not ours
  }
}

import {
  InvalidInputError,
  NetworkTimeoutError,
  RateLimitError,
  SynapError,
  type RawContext,
} from '@maximem/synap-js-sdk';

async function safeFetchContext(
  conversationId: string,
  query: string,
): Promise<RawContext | null> {
  // Fetch context with graceful degradation.
  try {
    return await sdk.conversation.context.fetch({
      conversation_id: conversationId,
      search_query: [query],
      mode: 'fast',
    });
  } catch (e) {
    if (e instanceof InvalidInputError) {
      console.info('Malformed conversation_id %s, skipping memory', conversationId);
      return null;
    }
    if (e instanceof NetworkTimeoutError) {
      console.warn('Timeout fetching context, proceeding without memory');
      return null;
    }
    if (e instanceof RateLimitError) {
      console.warn('Rate limited, retry after %ds', e.retryAfterSeconds);
      return null;
    }
    if (e instanceof SynapError) {
      console.error(
        'Unexpected error fetching context: %s (correlation_id=%s)',
        e, e.correlationId,
      );
      return null;
    }
    throw e;   // not ours
  }
}

Initialization Error Handling

from maximem_synap import (
    AuthenticationError,
    InvalidInputError,
    NetworkTimeoutError,
    SynapError,
)

async def initialize_with_fallback():
    """Initialize SDK with comprehensive error handling."""
    try:
        await sdk.initialize()
        return True

    except InvalidInputError:
        logger.error("Invalid instance ID. Check your configuration.")
        return False

    except AuthenticationError as e:
        logger.error(
            "Auth failed (no API key or invalid credentials): %s (correlation_id=%s)",
            e, e.correlation_id
        )
        return False

    except NetworkTimeoutError:
        logger.error("Cannot reach Synap Cloud. Check network connectivity.")
        return False

    except SynapError as e:
        logger.error(
            "Unexpected initialization error: %s (correlation_id=%s)",
            e, e.correlation_id
        )
        return False

import {
  AuthenticationError,
  InvalidInputError,
  NetworkTimeoutError,
  SynapError,
} from '@maximem/synap-js-sdk';

async function initializeWithFallback() {
  // Initialize SDK with comprehensive error handling.
  try {
    await sdk.initialize();
    return true;
  } catch (e) {
    if (e instanceof InvalidInputError) {
      console.error('Invalid instance ID. Check your configuration.');
      return false;
    }
    if (e instanceof AuthenticationError) {
      console.error(
        'Auth failed (no API key or invalid credentials): %s (correlation_id=%s)',
        e, e.correlationId,
      );
      return false;
    }
    if (e instanceof NetworkTimeoutError) {
      console.error('Cannot reach Synap Cloud. Check network connectivity.');
      return false;
    }
    if (e instanceof SynapError) {
      console.error(
        'Unexpected initialization error: %s (correlation_id=%s)',
        e, e.correlationId,
      );
      return false;
    }
    throw e;   // not ours
  }
}

import {
  AuthenticationError,
  InvalidInputError,
  NetworkTimeoutError,
  SynapError,
} from '@maximem/synap-js-sdk';

async function initializeWithFallback(): Promise<boolean> {
  // Initialize SDK with comprehensive error handling.
  try {
    await sdk.initialize();
    return true;
  } catch (e) {
    if (e instanceof InvalidInputError) {
      console.error('Invalid instance ID. Check your configuration.');
      return false;
    }
    if (e instanceof AuthenticationError) {
      console.error(
        'Auth failed (no API key or invalid credentials): %s (correlation_id=%s)',
        e, e.correlationId,
      );
      return false;
    }
    if (e instanceof NetworkTimeoutError) {
      console.error('Cannot reach Synap Cloud. Check network connectivity.');
      return false;
    }
    if (e instanceof SynapError) {
      console.error(
        'Unexpected initialization error: %s (correlation_id=%s)',
        e, e.correlationId,
      );
      return false;
    }
    throw e;   // not ours
  }
}

Full error reference

The hierarchy and handling patterns above cover how to catch and respond to each error. For the at-a-glance catalog (every SDK exception class with its transient/permanent type and common cause) see SDK Reference: Error handling. For the server-side wire codes those exceptions wrap (HTTP status, machine-readable code, and details shape) see Error Codes.

Next Steps

SDK Configuration

Customize retry policies, timeouts, and other SDK settings.

Initializing the SDK

Set up the SDK with proper error handling from the start.

Support

Contact Synap support with correlation IDs for issue resolution.

FAQ

Common questions about errors and troubleshooting.

JavaScript: typed error handling

Error classes are real classes, so instanceof narrowing works, and each carries a stable .code and a .transient flag:

import {
  RateLimitError,
  AuthenticationError,
  InsufficientCreditsError,
  isSynapError,
} from "@maximem/synap-js-sdk";

try {
  await synap.user.context.fetch({ user_id, customer_id });
} catch (error) {
  if (!isSynapError(error)) throw error;

  if (error instanceof RateLimitError) {
    console.warn(`Retry after ${error.retryAfterSeconds}s`);
  } else if (error instanceof AuthenticationError) {
    console.error("Check SYNAP_API_KEY");
  } else if (error instanceof InsufficientCreditsError) {
    console.error(
      `Short ${error.requiredCredits} credits (balance ${error.balanceCredits}). ` +
      `Top up: ${error.recoveryUrl}  Redeem: ${error.redeemUrl}`,
    );
  }
}

Transient errors are retried automatically. Ingestion is deliberately not retried when a failure leaves the outcome unknown, because a retry would store and bill twice.

Setup

SDK Guide

Overview

Full error reference →

Error Hierarchy

Transient Errors

NetworkTimeoutError

RateLimitError

ServiceUnavailableError

Permanent Errors

InvalidInputError

InvalidInstanceIdError

InvalidConversationIdError

AuthenticationError

ContextNotFoundError

SessionExpiredError

InsufficientCreditsError

AgentUnavailableError

ListeningAlreadyActiveError

ListeningNotActiveError

Stream health

Using correlation_id

Retry Policy Configuration

Retry Behavior

Disabling Retries

Customizing Retryable Errors

Common Error Handling Patterns

Catch-All with Transient/Permanent Distinction

Per-Operation Error Handling

Initialization Error Handling

Full error reference

Next Steps

SDK Configuration

Initializing the SDK

Support

FAQ

JavaScript: typed error handling

​Overview

Full error reference →

​Error Hierarchy

​Transient Errors

​NetworkTimeoutError

​RateLimitError

​ServiceUnavailableError

​Permanent Errors

​InvalidInputError

​InvalidInstanceIdError

​InvalidConversationIdError

​AuthenticationError

​ContextNotFoundError

​SessionExpiredError

​InsufficientCreditsError

​AgentUnavailableError

​ListeningAlreadyActiveError

​ListeningNotActiveError

​Stream health

​Using correlation_id

​Retry Policy Configuration

​Retry Behavior

​Disabling Retries

​Customizing Retryable Errors

​Common Error Handling Patterns

​Catch-All with Transient/Permanent Distinction

​Per-Operation Error Handling

​Initialization Error Handling

​Full error reference

​Next Steps

SDK Configuration

Initializing the SDK

Support

FAQ

​JavaScript: typed error handling

Overview

Error Hierarchy

Transient Errors

NetworkTimeoutError

RateLimitError

ServiceUnavailableError

Permanent Errors

InvalidInputError

InvalidInstanceIdError

InvalidConversationIdError

AuthenticationError

ContextNotFoundError

SessionExpiredError

InsufficientCreditsError

AgentUnavailableError

ListeningAlreadyActiveError

ListeningNotActiveError

Stream health

Using correlation_id

Retry Policy Configuration

Retry Behavior

Disabling Retries

Customizing Retryable Errors

Common Error Handling Patterns

Catch-All with Transient/Permanent Distinction

Per-Operation Error Handling

Initialization Error Handling

Full error reference

Next Steps

JavaScript: typed error handling