Skip to main content
View as Markdown

Error Handling & Best Practices - Content Management

Error Handling & Best Practices​

Error Handling​

  • Check the HTTP status code first.
  • If the status is not 200, parse the JSON error response. Key fields are usually:
    • code: A string identifier for the error (e.g., ESEARCH_SERVICE_DOWN, INVALID_KS).
    • message: A human-readable description of the error.
  • Common eSearch Errors:
    • ESEARCH_SERVICE_DOWN: The search service is temporarily unavailable. Consider retrying.
    • ELASTIC_SEARCH_QUERY_NOT_VALID: Check the syntax and structure of your searchParams.
    • PERMISSION_READ_ELASTIC_SEARCH_NOT_ALLOWED: The ks used does not have the necessary permissions.
  • Implement logging for errors to aid debugging.

Retry strategy: For transient errors (HTTP 5xx, ESEARCH_SERVICE_DOWN, timeouts), retry with exponential backoff: 1s, 2s, 4s, with jitter, up to 3 retries. For client errors (INVALID_KS, ELASTIC_SEARCH_QUERY_NOT_VALID, permission errors), fix the request before retrying — these will not resolve on their own.

Best Practices​

  • Use targeted field searches for performance. Unified searches (KalturaESearchUnifiedItem) query all fields and can be slower. Specify fieldName (e.g., NAME, CAPTIONS_CONTENT) when you know what you are searching.
  • Choose EXACT_MATCH vs PARTIAL intentionally. EXACT_MATCH (itemType=1) provides higher precision. PARTIAL (itemType=2) expands with synonyms for higher recall. Use ignoreSynonym=true in searchParams to disable synonym expansion when precision matters more.
  • Paginate with scroll-forward for large result sets. Elasticsearch caps at 10K results (500/page x 20 pages). For larger sets, use KalturaESearchRange on created_at with date windows.
  • Use aggregations for faceted counts. Aggregations return counts per value (media type, category, tag) without fetching full results — ideal for building filter UIs.
  • Use concrete objectTypes. Abstract types (KalturaESearchOrderByItem, KalturaESearchAggregationItem) return OBJECT_TYPE_ABSTRACT. Always use concrete types like KalturaESearchEntryOrderByItem.
  • Note the aggregation double nesting. The parameter path is searchParams[aggregations][aggregations][0] — the outer is the container, the inner is the array.
  • Caption timestamps are milliseconds. startsAt and endsAt in caption item data are integers in milliseconds. Divide by 1000 for seconds.