Error Codes

Complete reference of 45 error codes across 9 categories returned by the Search Service.

Error response formatjson

{
  "data": null,
  "error": {
    "code": "ERR_SEARCH_EXECUTION_FAILED",
    "message": "Search execution failed: index_not_found_exception",
    "http": 500
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant-uuid",
    "service": "search-svc"
  }
}

Input ValidationValidation

Code	HTTP	Description	Resolution
`ERR_SEARCH_QUERY_TOO_SHORT`	400	Search query must be at least {min} characters	Provide a query with at least 2 characters
`ERR_SEARCH_QUERY_TOO_LONG`	400	Search query must not exceed {max} characters	Shorten the query to 1000 characters or less
`ERR_SEARCH_INVALID_REQUEST`	400	Invalid request parameters	Check request body against API docs
`ERR_SEARCH_INVALID_ENTITY_TYPE`	400	Invalid entity type: {entityType}	Use: event, venue, artist, destination, brand
`ERR_SEARCH_INVALID_SORT_BY`	400	Invalid sort option: {sortBy}	Use: relevance, date, price, rating, distance
`ERR_SEARCH_INVALID_PAGE`	400	Page number must be greater than 0	Use page >= 1
`ERR_SEARCH_INVALID_LIMIT`	400	Limit must be between 1 and {max}	Use limit between 1 and 100
`ERR_SEARCH_INVALID_GEO_LOCATION`	400	Invalid geographic coordinates	Provide valid lat (-90 to 90) and lng (-180 to 180)
`ERR_SEARCH_INVALID_RADIUS`	400	Search radius must be between {min} and {max} km	Use radius between 1 and 500 km
`ERR_SEARCH_INVALID_DATE_RANGE`	400	Invalid date range	Ensure start_date is before end_date (ISO 8601)
`ERR_SEARCH_INVALID_PRICE_RANGE`	400	Invalid price range	Ensure min_price <= max_price, both >= 0

Search EngineOpenSearch

Code	HTTP	Description	Resolution
`ERR_SEARCH_ELASTICSEARCH_UNAVAILABLE`	503	Search service temporarily unavailable	Retry with exponential backoff
`ERR_SEARCH_ELASTICSEARCH_CONNECTION_FAILED`	502	Failed to connect to search engine	Check OpenSearch cluster health
`ERR_SEARCH_ELASTICSEARCH_TIMEOUT`	504	Search request timed out	Simplify query or reduce result count
`ERR_SEARCH_ELASTICSEARCH_ERROR`	500	Search engine error: {message}	Check OpenSearch logs for details
`ERR_SEARCH_EXECUTION_FAILED`	500	Search execution failed: {message}	Retry; check if indices exist for this tenant
`ERR_SEARCH_INDEX_NOT_FOUND`	404	Search index not found: {indexName}	Run POST /admin/indices/create to create indices
`ERR_SEARCH_ELASTICSEARCH_QUERY_FAILED`	500	Query construction or execution failed	Simplify search query and retry

Saved SearchesSaved Searches

Code	HTTP	Description	Resolution
`ERR_SEARCH_SAVED_SEARCH_NOT_FOUND`	404	Saved search not found	Verify the saved search ID exists
`ERR_SEARCH_SAVED_SEARCH_LIMIT_EXCEEDED`	429	Saved search limit exceeded ({limit})	Delete existing saved searches or upgrade tier
`ERR_SEARCH_SAVED_SEARCH_ALREADY_EXISTS`	409	Saved search with this name already exists	Use a different name
`ERR_SEARCH_SAVED_SEARCH_UNAUTHORIZED`	403	Not authorized to access this saved search	You can only access your own saved searches

Search AlertsAlerts

Code	HTTP	Description	Resolution
`ERR_SEARCH_ALERT_LIMIT_EXCEEDED`	429	Alert limit exceeded ({limit} active alerts)	Delete existing alerts or upgrade tier
`ERR_SEARCH_ALERT_NOT_FOUND`	404	Search alert not found	Verify the alert ID exists

Search HistoryHistory

Code	HTTP	Description	Resolution
`ERR_SEARCH_HISTORY_NOT_FOUND`	404	Search history not found	Verify the history entry ID
`ERR_SEARCH_HISTORY_RETENTION_EXPIRED`	410	Search history retention period expired	History entries are retained for 90 days

Rate Limits & QuotasRate Limiting & Quotas

Code	HTTP	Description	Resolution
`ERR_SEARCH_RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded. Retry in {retryAfter}s	Implement exponential backoff
`ERR_SEARCH_QUOTA_EXCEEDED`	429	Search quota exceeded for current period	Wait for quota reset or upgrade tier
`ERR_SEARCH_TIER_INSUFFICIENT`	403	Feature requires {requiredTier} tier	Upgrade subscription plan
`ERR_SEARCH_AI_CREDITS_INSUFFICIENT`	400	Insufficient AI credits (Required: {n})	Purchase AI credits or use non-semantic search
`ERR_SEARCH_FEATURE_NOT_AVAILABLE`	403	Feature not available: {feature}	Check tier requirements for this feature

AI ServicesAI & ML

Code	HTTP	Description	Resolution
`ERR_SEARCH_VOICE_SEARCH_FAILED`	502	Voice search processing failed	Retry; check audio file format (WAV/MP3)
`ERR_SEARCH_IMAGE_SEARCH_FAILED`	502	Image search processing failed	Retry; check image format (JPEG/PNG)
`ERR_SEARCH_NLP_SERVICE_UNAVAILABLE`	502	NLP service unavailable	Retry; AI Brain service may be restarting
`ERR_SEARCH_RAG_SERVICE_UNAVAILABLE`	502	Vector embedding service unavailable	Retry; rag-svc may be restarting on ECS Fargate
`ERR_SEARCH_EMBEDDING_GENERATION_FAILED`	502	Failed to generate search embeddings	Retry; check llm-orch-svc availability
`ERR_SEARCH_VOICE_UNAVAILABLE`	503	Voice search requires AI Brain STT	Contact admin to enable voice search
`ERR_SEARCH_VOICE_TRANSCRIPTION_EMPTY`	400	Could not transcribe audio input	Check audio quality and language
`ERR_SEARCH_IMAGE_UNAVAILABLE`	503	Image search requires AI Brain Service	Contact admin to enable image search
`ERR_SEARCH_IMAGE_ANALYSIS_EMPTY`	400	Could not extract text from image	Use a clearer image with readable text

Index AdministrationAdmin

Code	HTTP	Description	Resolution
`ERR_SEARCH_INDEX_CREATION_FAILED`	500	Failed to create search index	Check OpenSearch cluster capacity
`ERR_SEARCH_INDEX_DELETION_FAILED`	500	Failed to delete search index	Verify index exists and cluster is healthy
`ERR_SEARCH_REINDEX_FAILED`	500	Reindexing operation failed	Check source data and cluster health
`ERR_SEARCH_BULK_OPERATION_FAILED`	500	Bulk indexing operation failed	Reduce batch size and retry
`ERR_SEARCH_DOCUMENT_NOT_INDEXED`	404	Document not found in search index	Re-index the document
`ERR_SEARCH_FACET_NOT_FOUND`	404	Facet not found: {facet}	Use valid facet fields for this entity type

Authentication & AuthorizationAuth & Tenant

Code	HTTP	Description	Resolution
`ERR_SEARCH_UNAUTHORIZED`	401	Authentication required	Provide a valid JWT token in Authorization header
`ERR_SEARCH_FORBIDDEN`	403	Permission denied or tenant mismatch	Check roles and ensure x-tenant-id matches JWT
`ERR_SEARCH_INVALID_TENANT`	400	Invalid tenant identifier	Provide a valid UUID for x-tenant-id
`ERR_SEARCH_CACHE_ERROR`	500	Cache operation failed	Retry; Redis may be temporarily unavailable
`ERR_SEARCH_INTERNAL_ERROR`	500	Internal server error	Retry; if persistent, report with request_id
`ERR_SEARCH_BOOTSTRAP_FAILED`	503	Service initializing	Retry in a few seconds (Lambda cold start)