Skip to main content
{
  "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, bootstrap keys, certificates, and credentials.
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": {}
}
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"]
  }
}
HTTP Status: 401Description: The provided bootstrap key is not valid. It may have been revoked, does not exist, or does not match the stored hash.Common Causes:
  • Typographical error in the bootstrap key
  • Key was revoked via the Dashboard or API
  • Key was generated for a different instance
Resolution:
  • Generate a new bootstrap key from the Dashboard
  • Ensure the key matches the target instance
  • Check that the key has not been revoked in the webhook logs
{
  "error": "Bootstrap key is not valid",
  "code": "BOOTSTRAP_KEY_INVALID",
  "details": {
    "instance_id": "inst_f1e2d3c4b5a69078"
  }
}
HTTP Status: 401Description: The bootstrap key has expired. Bootstrap keys are valid for 24 hours after generation.Common Causes:
  • Key was generated more than 24 hours ago
  • Clock skew between the client and Synap servers
Resolution:
  • Generate a new bootstrap key
  • Use the key promptly after generation
{
  "error": "Bootstrap key has expired",
  "code": "BOOTSTRAP_KEY_EXPIRED",
  "details": {
    "expired_at": "2025-01-15T16:00:00Z",
    "instance_id": "inst_f1e2d3c4b5a69078"
  }
}
HTTP Status: 401Description: The bootstrap key has already been used. Bootstrap keys are single-use.Common Causes:
  • The SDK already bootstrapped successfully with this key
  • Another process or deployment used the key first
Resolution:
  • If the original bootstrap succeeded, no action is needed — the SDK has its certificate
  • If the original bootstrap failed, generate a new bootstrap key
{
  "error": "Bootstrap key has already been consumed",
  "code": "BOOTSTRAP_KEY_CONSUMED",
  "details": {
    "consumed_at": "2025-01-15T12:00:00Z",
    "instance_id": "inst_f1e2d3c4b5a69078"
  }
}
HTTP Status: 401Description: The mTLS client certificate has expired. Certificates are valid for 7 days with a 48-hour grace period.Common Causes:
  • The SDK was offline for more than 7 days and missed automatic rotation
  • Certificate rotation was disabled or failed silently
Resolution:
  • Restart the SDK to trigger automatic certificate renewal
  • If within the 48-hour grace period, the SDK will renew automatically
  • If beyond the grace period, a new bootstrap key is required
{
  "error": "Client certificate has expired",
  "code": "CERTIFICATE_EXPIRED",
  "details": {
    "expired_at": "2025-01-15T00:00:00Z",
    "grace_period_until": "2025-01-17T00:00:00Z"
  }
}
HTTP Status: 401Description: The provided credential (API key or certificate) 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
  • Certificate was issued by an untrusted CA
  • Credential binding mismatch (certificate bound to a different instance)
Resolution:
  • Check for recent credential rotation events in the audit log
  • Verify the SDK is using the correct certificate 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.
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"
    }
  }
}
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.
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"
  }
}
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"
  }
}
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"
  }
}

​
Configuration Errors

Errors specific to the MACA configuration workflow.
HTTP Status: 409Description: The requested configuration operation conflicts with the current state.Common Causes:
  • Attempting to apply a configuration that has not been approved
  • Attempting to review a configuration that has already been reviewed
  • Concurrent configuration updates creating a race condition
Resolution:
  • Check the configuration status before performing operations
  • Ensure the configuration has been approved before applying
  • Retry with the latest version if a race condition occurred
{
  "error": "Configuration operation conflicts with current state",
  "code": "CONFIG_CONFLICT",
  "details": {
    "config_id": "maca_cfg_5e6f7a8b",
    "current_status": "pending_review",
    "requested_action": "apply",
    "required_status": "approved"
  }
}
HTTP Status: 400Description: The submitted configuration failed schema or business validation.Common Causes:
  • Invalid YAML syntax in the configuration
  • Field values outside allowed ranges (e.g., negative embedding dimension)
  • Incompatible configuration combinations (e.g., graph queries enabled but graph store disabled)
Resolution:
  • Review the details.validation_errors array for specific issues
  • Refer to the Configuration Schema for valid values
{
  "error": "Configuration validation failed",
  "code": "CONFIG_VALIDATION_ERROR",
  "details": {
    "validation_errors": [
      {
        "field": "storage.vector.embedding_dimension",
        "message": "Value must be between 64 and 4096",
        "value": -1
      },
      {
        "field": "retrieval.context_budget",
        "message": "Value must be between 256 and 32768",
        "value": 100
      }
    ]
  }
}
HTTP Status: 409Description: The configuration version is already the active configuration for this instance.Common Causes:
  • Attempting to apply a configuration that is already active
  • Race condition where two apply operations executed simultaneously
Resolution:
  • Check the current active configuration before applying
  • No action needed if the desired config is already active
{
  "error": "This configuration is already active",
  "code": "CONFIG_ALREADY_ACTIVE",
  "details": {
    "config_id": "maca_cfg_5e6f7a8b",
    "applied_at": "2025-01-15T17:00:00Z"
  }
}

​
System Errors

Errors caused by internal system issues or temporary unavailability.
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"
  }
}
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 synap.exceptions import (
    SynapAuthError,       # 401, 403
    SynapNotFoundError,   # 404
    SynapConflictError,   # 409
    SynapRateLimitError,  # 429
    SynapServerError,     # 500, 503
    SynapValidationError, # 400
)

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