> ## Documentation Index > Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt > Use this file to discover all available pages before exploring further. # Error Codes > All Synap API errors follow a consistent format with a human-readable `error` message, a machine-readable `code`, and an optional `details` object with additional context. ```json theme={null} { "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. **HTTP Status:** `401` **Description:** 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 ` 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 ```json theme={null} { "error": "Missing or invalid authentication credentials", "code": "UNAUTHORIZED", "details": {} } ``` **HTTP Status:** `403` **Description:** 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 ```json theme={null} { "error": "Insufficient permissions for this operation", "code": "FORBIDDEN", "details": { "required_permission": "instances:write", "current_permissions": ["instances:read", "memories:read"] } } ``` **HTTP Status:** `401` **Description:** 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 ```json theme={null} { "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. **HTTP Status:** `400` **Description:** 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 ```json theme={null} { "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" } } } ``` **HTTP Status:** `429` **Description:** 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 ```json theme={null} { "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. **HTTP Status:** `404` **Description:** 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_` * List instances via `GET /dashboard/instances` to find valid IDs * Check the Dashboard for archived instances ```json theme={null} { "error": "Instance not found", "code": "INSTANCE_NOT_FOUND", "details": { "instance_id": "inst_nonexistent123456" } } ``` **HTTP Status:** `404` **Description:** The specified conversation could not be resolved for this instance. Fetching context for a brand-new `conversation_id` that simply has no messages yet does **not** raise this error. Context retrieval returns an empty result in that case. This error is reserved for conversations that cannot be resolved at all (wrong instance, malformed id, or purged data). **Common Causes:** * Conversation ID is incorrect or malformed * 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 ```json theme={null} { "error": "Conversation not found", "code": "CONVERSATION_NOT_FOUND", "details": { "conversation_id": "conv_nonexistent" } } ``` **HTTP Status:** `404` **Description:** 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 ```json theme={null} { "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. **HTTP Status:** `500` **Description:** 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](https://synap.maximem.ai/status) for known incidents ```json theme={null} { "error": "An internal error occurred. Please try again.", "code": "INTERNAL_ERROR", "details": { "correlation_id": "req_7f3a2b1c-9d4e-4f5a-8b6c-1d2e3f4a5b6c" } } ``` **HTTP Status:** `503` **Description:** 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](https://synap.maximem.ai/status) for planned maintenance * Contact support if the issue persists beyond the maintenance window ```json theme={null} { "error": "Service is temporarily unavailable. Please retry.", "code": "SERVICE_UNAVAILABLE", "details": { "retry_after_seconds": 60, "reason": "maintenance" } } ``` *** ## Error Handling Best Practices Always use the `code` field for programmatic error handling, not the `error` message. Error messages may be localized or reworded. Retry `429`, `500`, and `503` errors with exponential backoff and jitter. Never retry `400`, `401`, `403`, or `404` errors without changing the request. Log the `X-Correlation-Id` from every error response. Include it when contacting support to expedite troubleshooting. 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: ```python theme={null} import uuid from maximem_synap import ( AuthenticationError, # 401, 403 ContextNotFoundError, # 404 RateLimitError, # 429 ServiceUnavailableError,# 503 InvalidInputError, # 400 SynapError, # base class for all SDK errors ) # conversation_id must be a valid UUID try: context = await sdk.conversation.context.fetch( conversation_id=str(uuid.uuid4()), 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](/sdk/error-handling).