Error Codes

Complete reference for all API error codes, their meanings, and how to handle them gracefully in your application.

Error Response Format

All error responses follow a consistent format:

Error Response Format

{
  "detail": "Error message describing what went wrong"
}

The detail field contains a human-readable error message that explains what went wrong.

Error Codes

400

Bad Request

The request is malformed or missing required fields

Example Response

{
  "detail": "Field 'user_id' is required"
}

Common Causes

Missing required fields
Invalid field types
Malformed JSON
Invalid enum values

401

Unauthorized

The API key is missing, invalid, or expired

Example Response

{
  "detail": "Invalid API key"
}

Common Causes

Missing X-API-Key header
Invalid API key format
Revoked or deleted API key
Expired API key

403

Forbidden

Policy violation - the requested purpose is not allowed for the scope

Example Response

{
  "detail": "Purpose class 'task_execution' not allowed for scope 'preferences'"
}

Common Causes

Purpose not allowed for scope (policy violation)
Revoked revocation token used in continue operation
Expired revocation token

404

Not Found

The requested resource was not found

Example Response

{
  "detail": "Revocation token not found"
}

Common Causes

Invalid revocation token
Revocation token already revoked
Revocation token expired

422

Unprocessable Entity

The request is well-formed but contains semantic errors

Example Response

{
  "detail": "Invalid scope value. Must be one of: preferences, constraints, communication, accessibility, schedule, attention"
}

Common Causes

Invalid scope value
Invalid domain format
Invalid value_json structure
TTL value out of range

429

Too Many Requests

Rate limit exceeded. Too many requests in a given time period

Example Response

{
  "detail": "Rate limit exceeded. Please try again later."
}

Common Causes

Exceeded rate limit for your API key
Too many requests in a short time period

500

Internal Server Error

An unexpected error occurred on the server

Example Response

{
  "detail": "An internal error occurred. Please try again later."
}

Common Causes

Server-side error
Database connection issue
Unexpected system error

Error Handling Examples

Error Handling

from memory_scope import MemoryScopeClient
from memory_scope.exceptions import (
    PolicyDeniedError,
    InvalidRequestError,
    AuthenticationError,
    NotFoundError,
    RateLimitError
)

client = MemoryScopeClient(api_key="your-api-key")

try:
    result = client.read_memory(
        user_id="user123",
        scope="preferences",
        domain="food",
        purpose="generate food recommendations"
    )
except PolicyDeniedError as e:
    # Handle policy denial (403)
    print(f"Access denied: {e.message}")
    # Fallback behavior
    result = {"likes": [], "dislikes": []}
except InvalidRequestError as e:
    # Handle invalid request (400, 422)
    print(f"Invalid request: {e.message}")
    # Fix the request and retry
except AuthenticationError as e:
    # Handle authentication error (401)
    print(f"Authentication failed: {e.message}")
    # Check API key
except NotFoundError as e:
    # Handle not found (404)
    print(f"Resource not found: {e.message}")
except RateLimitError as e:
    # Handle rate limit (429)
    print(f"Rate limit exceeded: {e.message}")
    # Implement exponential backoff
    import time
    time.sleep(60)  # Wait before retrying
except Exception as e:
    # Handle other errors (500, etc.)
    print(f"Unexpected error: {e}")
    # Log error and notify support

Best Practices

Handle All Errors: Always handle errors gracefully. Don't let unhandled errors crash your application.
Provide User-Friendly Messages: Translate technical error messages into user-friendly messages when displaying to end users.
Log Errors: Log errors with sufficient context for debugging, but don't expose sensitive information in user-facing messages.
Implement Retry Logic: For transient errors (500, 429), implement retry logic with exponential backoff.
Handle Policy Denials Gracefully: Policy denials (403) are expected in some cases. Handle them gracefully with fallback behavior.
Validate Input: Validate input before making API requests to avoid 400 and 422 errors.
Monitor Error Rates: Monitor error rates in your application to detect issues early.

Rate Limiting

If you receive a 429 Too Many Requests error, implement exponential backoff and retry the request after the specified time. See Rate Limits for more information.