Error Codes

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "details": {
    "field": "additional context"
  }
}

Use the code field for programmatic error handling. The error message may change between API versions, but code values are stable.

Authentication Errors

Errors related to API keys and credentials.

UNAUTHORIZED

HTTP Status: 401Description: The request is missing authentication credentials or the provided credentials are not recognized.Common Causes:

Missing Authorization header
Malformed bearer token (e.g., missing Bearer prefix)
API key does not exist in the system

Resolution:

Verify the Authorization: Bearer <api_key> header is present
Check that the API key is correctly copied without leading or trailing whitespace
Generate a new API key from the Dashboard if the key may have been deleted

{
  "error": "Missing or invalid authentication credentials",
  "code": "UNAUTHORIZED",
  "details": {}
}

FORBIDDEN

HTTP Status: 403Description: The credentials are valid but do not have permission to perform the requested operation.Common Causes:

API key does not have access to the requested instance
Attempting to access another client’s resources
Attempting an admin operation with a read-only key

Resolution:

Verify the API key has the correct permissions in the Dashboard
Check that the instance belongs to the same client as the API key
Use an admin-level API key for management operations

{
  "error": "Insufficient permissions for this operation",
  "code": "FORBIDDEN",
  "details": {
    "required_permission": "instances:write",
    "current_permissions": ["instances:read", "memories:read"]
  }
}

CREDENTIAL_INVALID

HTTP Status: 401Description: The provided API key is structurally valid but does not match any known credential in the system.Common Causes:

API key was rotated and the old key is being used
API key was revoked from the dashboard

Resolution:

Check for recent credential rotation events in the audit log
Verify the SDK is using the correct API key for the target instance
Contact support with the correlation ID if the issue persists

{
  "error": "Credential does not match any known credential",
  "code": "CREDENTIAL_INVALID",
  "details": {}
}

Input Validation Errors

Errors caused by invalid request parameters, missing required fields, or malformed data.

INVALID_INPUT

HTTP Status: 400Description: One or more request parameters are invalid, missing, or malformed.Common Causes:

Missing required field in the request body
Field value is the wrong type (e.g., string instead of integer)
Field value is out of the allowed range
Invalid enum value

Resolution:

Check the details field for specific information about which fields are invalid
Refer to the endpoint documentation for required fields and valid values

{
  "error": "Invalid input parameters",
  "code": "INVALID_INPUT",
  "details": {
    "fields": {
      "document_type": "Must be one of: ai-chat-conversation, human-chat-conversation, support-ticket, knowledge-article, document, email, note",
      "mode": "Required field is missing"
    }
  }
}

RATE_LIMITED

HTTP Status: 429Description: The API key has exceeded its rate limit for the current window.Common Causes:

High-volume ingestion without batching
Polling loops without backoff
Multiple processes sharing the same API key

Resolution:

Implement exponential backoff with jitter
Use the Retry-After header to determine when to retry
Use batch endpoints for high-volume operations
Contact support to increase your rate limit

{
  "error": "Rate limit exceeded. Retry after 30 seconds.",
  "code": "RATE_LIMITED",
  "details": {
    "limit": 600,
    "remaining": 0,
    "reset_at": "2025-01-15T10:01:00Z",
    "retry_after_seconds": 30
  }
}

Resource Not Found Errors

Errors returned when a requested resource does not exist.

INSTANCE_NOT_FOUND

HTTP Status: 404Description: The specified instance does not exist or is not accessible with the current credentials.Common Causes:

Typographical error in the instance ID
Instance was archived or deleted
Instance belongs to a different client

Resolution:

Verify the instance ID format: inst_<hex16>
List instances via GET /dashboard/instances to find valid IDs
Check the Dashboard for archived instances

{
  "error": "Instance not found",
  "code": "INSTANCE_NOT_FOUND",
  "details": {
    "instance_id": "inst_nonexistent123456"
  }
}

CONVERSATION_NOT_FOUND

HTTP Status: 404Description: The specified conversation does not exist for this instance.Common Causes:

Conversation ID is incorrect
Conversation was started on a different instance
Conversation data has been purged due to retention policies

Resolution:

Verify the conversation ID
Check that the conversation belongs to the correct instance
Review retention policies if the conversation may have expired

{
  "error": "Conversation not found",
  "code": "CONVERSATION_NOT_FOUND",
  "details": {
    "conversation_id": "conv_nonexistent"
  }
}

CONFIG_NOT_FOUND

HTTP Status: 404Description: The specified configuration version does not exist.Common Causes:

Typographical error in the config ID
Configuration was from a different instance
Configuration version was superseded and purged

Resolution:

List configuration versions via GET /instances/{id}/memory-architecture/versions
Verify the config ID matches the target instance

{
  "error": "Configuration version not found",
  "code": "CONFIG_NOT_FOUND",
  "details": {
    "config_id": "maca_cfg_nonexistent",
    "instance_id": "inst_f1e2d3c4b5a69078"
  }
}

System Errors

Errors caused by internal system issues or temporary unavailability.

INTERNAL_ERROR

HTTP Status: 500Description: An unexpected error occurred on Synap’s side. This is not caused by the request and should be reported if it persists.Common Causes:

Unhandled exception in the processing pipeline
Database connectivity issue
Upstream service failure

Resolution:

Retry the request with exponential backoff
If the error persists, contact support with the X-Correlation-Id header value
Check the status page for known incidents

{
  "error": "An internal error occurred. Please try again.",
  "code": "INTERNAL_ERROR",
  "details": {
    "correlation_id": "req_7f3a2b1c-9d4e-4f5a-8b6c-1d2e3f4a5b6c"
  }
}

SERVICE_UNAVAILABLE

HTTP Status: 503Description: Synap is temporarily unable to process the request. The service will recover automatically.Common Causes:

Planned maintenance window
Auto-scaling event in progress
Dependent service temporarily unavailable

Resolution:

Retry with exponential backoff using the Retry-After header
Check the status page for planned maintenance
Contact support if the issue persists beyond the maintenance window

{
  "error": "Service is temporarily unavailable. Please retry.",
  "code": "SERVICE_UNAVAILABLE",
  "details": {
    "retry_after_seconds": 60,
    "reason": "maintenance"
  }
}

Error Handling Best Practices

Use the code field

Always use the code field for programmatic error handling, not the error message. Error messages may be localized or reworded.

Implement retries

Retry 429, 500, and 503 errors with exponential backoff and jitter. Never retry 400, 401, 403, or 404 errors without changing the request.

Log correlation IDs

Log the X-Correlation-Id from every error response. Include it when contacting support to expedite troubleshooting.

Validate locally first

Validate inputs on the client side before sending requests. This reduces unnecessary API calls and provides faster feedback to users.

SDK Error Handling

The Python SDK wraps API errors in typed exceptions:

from maximem_synap import (
    AuthenticationError,    # 401, 403
    ContextNotFoundError,   # 404
    RateLimitError,         # 429
    ServiceUnavailableError,# 503
    InvalidInputError,      # 400
    SynapError,             # base class for all SDK errors
)

try:
    context = await sdk.conversation.context.fetch(
        conversation_id="conv_abc123",
        search_query=["user preferences"],
    )
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds.")
except ContextNotFoundError as e:
    print(f"Conversation not found: {e.details}")
except ServiceUnavailableError as e:
    print(f"Server unavailable. Correlation ID: {e.correlation_id}")

For the full list of SDK exception classes and which to catch when, see SDK Error Handling.

Introduction

Lifecycle

Memory ingestion

Memory management

Conversation

Conversation context

Scoped context

Real-time streaming

Cache management

Credits & billing

Reference

Authentication Errors

Input Validation Errors

Resource Not Found Errors

System Errors

Error Handling Best Practices

Use the code field

Implement retries

Log correlation IDs

Validate locally first

SDK Error Handling

Introduction

Lifecycle

Memory ingestion

Memory management

Conversation

Conversation context

Scoped context

Real-time streaming

Cache management

Credits & billing

Reference

Documentation Index

​Authentication Errors

​Input Validation Errors

​Resource Not Found Errors

​System Errors

​Error Handling Best Practices

Use the code field

Implement retries

Log correlation IDs

Validate locally first

​SDK Error Handling

Authentication Errors

Input Validation Errors

Resource Not Found Errors

System Errors

Error Handling Best Practices

SDK Error Handling