---
title: Error Handling & Best Practices
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/esearch-reference
---

## 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.