API Reference

Rate Limits & Errors

Classify HTTP and SDK errors before choosing the next application action. Do not hardcode an undocumented quota.

Handle unsuccessful requests

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
    project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
    end_user_id="usr_7f3a9c2e",
)

from memorysync import MemorySyncError, RateLimitError

try:
    result = client.query("What preferences are known?", k=5)
except RateLimitError as error:
    print("Rate limited", error.retry_after_seconds)
except MemorySyncError as error:
    print("Request failed", error)

Choose the next action

Status	Meaning	Next action
`2xx`	The request completed with an operation-specific result.	Read the documented body; an empty or skipped result can be valid.
`400`, `409`, or `422`	The fields or requested change are invalid.	Correct the request rather than waiting.
`401` or `403`	Authentication or project access failed.	Correct server credentials or scope.
`404`	The resource is unavailable in this scope.	Check scope and ID; show a not-found state.
`429`	The request is rate limited.	Use returned error metadata and a bounded application fallback.
`5xx`	The service could not complete the request.	Preserve a recoverable state and avoid assuming a write outcome.

Illustrative error response

429-response.json

{"detail":"Rate limited","retry_after":2}

Keep error handling safe

SDK error classes

Condition	Python	Node.js	Typical action
Authentication or access	`AuthError`	`AuthError`	Correct credentials or authorized scope.
Invalid input	`ValidationError`	`ValidationError`	Correct fields; do not retry unchanged.
Unavailable resource	`NotFoundError`	`NotFoundError`	Check scope and show a not-found state.
Rate limited	`RateLimitError`	`RateLimitError`	Use returned retry metadata when present.
Service failure	`ServerError`	`ServerError`	Keep the task recoverable and reconcile writes.
Network or timeout	`MemorySyncError`	`MemorySyncError`	Treat write outcome as uncertain.

Decide whether to retry

What kind of failure occurred?

Invalid request or authentication

The same request will fail again.

Use: Correct the request, credential, or scope before another call.

Rate limit with retry metadata

The service supplied a wait signal.

Use: Wait as directed, bound the retry count, and preserve a user fallback.

Read failed with a service or network error

No mutation is involved.

Use: Retry according to your product policy or continue without memory context.

Write response is uncertain

The connection ended before a reliable result was received.

Use: Reconcile through Get or Query before repeating a potentially duplicate action.

Build resilient error handling

Catch the most specific SDK error class before the base error class.
Keep human-readable messages separate from machine decisions.
Do not assume every 2xx means a new record was created; inspect operation-specific bodies.
Do not expose raw service errors or memory content directly to end users.
Record safe correlation data for support while excluding credentials and sensitive payloads.

Authentication

Correct 401 and 403 responses.

Add Memory

Handle created and skipped writes.

Bulk Add

Inspect every item in a 207 response.

Was this page helpful?

← Previous