algoliasearch

Postconditions — what we check

• search · search-no-try-catch

  error
  Whensearch() / searchSingleIndex() called in async context without surrounding try/catch. Any network failure, invalid API key (401), missing index (404), or rate limit (429) results in an unhandled rejected Promise.
  ThrowsApiError (status 401/403/404/429) — thrown immediately, not retried. RetryError — thrown when all Algolia hosts are unreachable.
  Required handlingCaller MUST wrap search calls in try/catch. Handle at minimum: - ApiError for API-level failures (check err.status or err.name === 'ApiError') - RetryError / network errors for connectivity failures Return a sensible empty result or error response — do NOT crash the request.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• searchSingleIndex · searchsingleindex-no-try-catch

  error
  WhensearchSingleIndex() called without surrounding try/catch.
  ThrowsApiError on 4xx responses. RetryError when all hosts unreachable.
  Required handlingCaller MUST wrap in try/catch. Same handling as search().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• saveObject · saveobject-no-try-catch

  error
  WhensaveObject() called without surrounding try/catch. Indexing failure (invalid API key, insufficient write ACL, malformed record) is silently swallowed.
  ThrowsApiError — 401 (invalid key), 403 (missing write ACL), 400 (malformed record). RetryError — network failure.
  Required handlingCaller MUST wrap in try/catch. Indexing failures in production apps (webhooks, API routes, background jobs) must be logged and optionally retried. Silent failures cause search index to diverge from source of truth.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• saveObjects · saveobjects-no-try-catch

  error
  WhensaveObjects() called without surrounding try/catch. Batch indexing failure results in entire batch failing silently.
  ThrowsApiError — 401, 403, 400 (malformed records), 413 (request too large). RetryError — network failure.
  Required handlingCaller MUST wrap in try/catch. For large batches, log the failure with batch size for debugging. Consider splitting large batches if 413 errors occur.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• getObject · getobject-no-try-catch

  error
  WhengetObject() called without surrounding try/catch. Object not found (404) crashes the caller.
  ThrowsApiError with status 404 when object does not exist. ApiError with status 401/403 for auth failures. RetryError for network failures.
  Required handlingCaller MUST wrap in try/catch. Handle 404 explicitly — the object may have been deleted. Return null or a sensible default rather than crashing.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• getObjects · getobjects-no-try-catch

  error
  WhengetObjects() called without surrounding try/catch. Auth failure or network error crashes the caller.
  ThrowsApiError on auth failures (401/403). RetryError on network failures.
  Required handlingCaller MUST wrap in try/catch. Note: missing individual objects return null results, not errors. But API/network errors still throw.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• deleteObject · deleteobject-no-try-catch

  error
  WhendeleteObject() called without surrounding try/catch. Auth or network failure silently fails, leaving stale data in the search index.
  ThrowsApiError on auth failures (401/403) or invalid index (400). RetryError on network failures.
  Required handlingCaller MUST wrap in try/catch. Unhandled delete failures leave stale records in the search index, causing deleted items to appear in search results.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• deleteObjects · deleteobjects-no-try-catch

  error
  WhendeleteObjects() called without surrounding try/catch.
  ThrowsApiError on auth failures (401/403). RetryError on network failures.
  Required handlingCaller MUST wrap in try/catch. Failed batch deletes leave stale records in index.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• waitForTask · waitfortask-no-try-catch

  error
  WhenwaitForTask() called without surrounding try/catch.
  ThrowsApiError — task failed or polling encountered an error. RetryError — network failure during polling.
  Required handlingCaller MUST wrap in try/catch. Task failures mean data was not indexed. Log task ID for debugging.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• setSettings · setsettings-no-try-catch

  error
  WhensetSettings() called without surrounding try/catch. Invalid settings or auth failure silently leaves index misconfigured.
  ThrowsApiError — 400 (invalid settings), 401/403 (auth), 422 (unprocessable entity). RetryError — network failure.
  Required handlingCaller MUST wrap in try/catch. Failed settings updates leave the index with incorrect search configuration.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• replaceAllObjects · replaceall-no-try-catch

  error
  WhenreplaceAllObjects() called without surrounding try/catch. Partial failure during the atomic swap may leave index in inconsistent state.
  ThrowsApiError — auth, invalid objects, rate limit. RetryError — network failure.
  Required handlingCaller MUST wrap in try/catch. This is a critical operation — partial failure can leave the index empty or in an inconsistent state.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• partialUpdateObject · partialupdateobject-no-try-catch

  error
  WhenpartialUpdateObject() or partialUpdateObjects() called without surrounding try/catch. Auth failure or network error crashes the caller. Common in update webhooks and background sync jobs.
  ThrowsApiError (status 401/403) — invalid or insufficient API key (missing addObject ACL). ApiError (status 400) — malformed attributesToUpdate payload. RetryError — all Algolia hosts unreachable.
  Required handlingCaller MUST wrap in try/catch. Missing addObject ACL returns 403 and will never succeed without a key rotation — log the error and alert, do not silently retry. Partial update failures leave search data stale (e.g. status field not updated after a payment event).
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[2]
• clearObjects · clearobjects-no-try-catch

  error
  WhenclearObjects() called without surrounding try/catch. Failure during a reindex pipeline leaves the index in an inconsistent state — records may be partially cleared or not cleared at all.
  ThrowsApiError (status 400) — bad request or invalid arguments. ApiError (status 402) — feature not enabled on the current Algolia plan. ApiError (status 403) — missing deleteIndex ACL on the API key. ApiError (status 404) — index does not exist. RetryError — all Algolia hosts unreachable during the operation.
  Required handlingCaller MUST wrap in try/catch. A 402 error indicates a plan limitation that will never succeed without a plan upgrade — do not retry. A 404 means the index was already deleted or never created. In reindex pipelines, failure here means the subsequent saveObjects() will add to stale data, not replace it.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[3]
• searchForFacetValues · searchforfacetvalues-no-try-catch

  error
  WhensearchForFacetValues() called without surrounding try/catch. Auth failure or network error crashes the caller. Common in faceted search UIs where a failed autocomplete crashes the search page.
  ThrowsApiError (status 401/403) — invalid or insufficient API key (missing search ACL). ApiError (status 404) — index not found. RetryError — all Algolia hosts unreachable.
  Required handlingCaller MUST wrap in try/catch. Return empty array on failure rather than crashing — facet search failures should degrade gracefully (e.g. show no autocomplete suggestions rather than crashing the search UI).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• deleteBy · deleteby-no-try-catch

  error
  WhendeleteBy() called without surrounding try/catch. Empty or invalid filters cause an ApiError (the operation explicitly rejects empty filters). Network errors cause a RetryError.
  ThrowsApiError (status 400) — empty filters object passed; the API explicitly rejects empty filters to prevent accidental deletion of all records. ApiError (status 403) — missing deleteIndex ACL. RetryError — all Algolia hosts unreachable.
  Required handlingCaller MUST wrap in try/catch AND validate that filters are non-empty before calling. An empty deleteByParams object throws ApiError 400. This is a common bug when filter values come from user input or upstream data that can be empty.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[5]
• partialUpdateObjects · partialupdateobjects-no-try-catch

  error
  WhenpartialUpdateObjects() called without surrounding try/catch. Common in webhook handlers and background sync jobs that update many records (e.g. update search data after bulk database events). Auth failure, invalid payload, or rate limits cause all batches to fail silently.
  ThrowsApiError (status 400) — malformed attributesToUpdate payload. ApiError (status 402) — feature not enabled on the current Algolia plan. ApiError (status 403) — missing addObject ACL on the API key. ApiError (status 404) — index not found. RetryError — all Algolia hosts unreachable.
  Required handlingCaller MUST wrap in try/catch. For large batch updates, log the object count and batch size for debugging. If createIfNotExists=false is used, the response does not indicate how many objects were skipped — callers cannot distinguish "updated" from "silently skipped" without separate verification.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[6]
• partialUpdateObjects · partialupdateobjects-silent-skip-on-missing

  warning
  WhenpartialUpdateObjects() is called with createIfNotExists=false (or the default createIfNotExists=true is intended to update existing records only), but the objectIDs in the batch do not exist in the index. With createIfNotExists=false, missing objects are silently skipped — the response is a success (BatchResponse[]) with no indication that objects were not found. With createIfNotExists=true (default), missing objects are CREATED, which may also be unexpected if the intent was to update-only.
  ThrowsDoes not throw. Returns BatchResponse[] even when all objects were missing. No error, no per-object status in the response.
  Required handlingWhen updating specific records, verify their existence with getObject() or getObjects() before calling partialUpdateObjects() if missing-object silencing is unacceptable. Or use saveObjects() (which always creates/replaces) when object existence is uncertain. If using createIfNotExists=false for "update-only" semantics, log and monitor the case where no updates are expected but the call succeeds — silent skips are invisible.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[6]
• addOrUpdateObject · addorupdateobject-no-try-catch

  error
  WhenaddOrUpdateObject() called without surrounding try/catch. Throws synchronous native Error if required parameters (indexName, objectID, body) are missing. Also throws ApiError on API failures and RetryError on network failures. Common in data synchronization flows where external data is mapped to Algolia records by a known objectID (e.g. database ID).
  ThrowsError (native, synchronous) — if indexName, objectID, or body is missing/falsy. ApiError (status 400) — malformed record body. ApiError (status 402) — feature not enabled on plan. ApiError (status 403) — missing addObject ACL on the API key. ApiError (status 404) — index not found. RetryError — all Algolia hosts unreachable.
  Required handlingCaller MUST wrap in try/catch. Handle both synchronous parameter validation errors (native Error) and asynchronous API errors (ApiError, RetryError). This method REPLACES the entire record — ensure the body contains all desired attributes, not just the ones being updated (use partialUpdateObject for partial updates).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• indexExists · indexexists-auth-network-throw

  error
  WhenindexExists() called without surrounding try/catch. Callers commonly omit try/catch because the method "returns a boolean" and feels safe. But 401 (invalid API key), 403 (missing search ACL), and RetryError (network failure) still throw — they are not caught internally. Only 404 is caught and converted to false. This is a common false-safety assumption.
  ThrowsApiError (status 401) — invalid API key. ApiError (status 403) — missing search ACL on the API key. RetryError — all Algolia hosts unreachable. Note: ApiError (status 404) is caught internally and returned as false.
  Required handlingCaller MUST wrap in try/catch even though the method returns a boolean. The 404 case is safe (returns false), but auth and network failures still throw: try { const exists = await client.indexExists({ indexName }); if (!exists) { // Index needs to be created } } catch (error) { if (error instanceof ApiError) { console.error('Auth or API error checking index:', error.status, error.message); } throw error; }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• waitForAppTask · waitforapptask-max-retries-exceeded

  error
  WhenwaitForAppTask() called without surrounding try/catch. If the app-level task does not reach "published" status within maxRetries attempts (default 50 retries × up to 5000ms per retry = ~4 minutes total), throws an Error with "The maximum number of retries exceeded." This is a native Error, not an ApiError or RetryError. Also throws if getAppTask() polling encounters an API or network error.
  ThrowsError (native) — "The maximum number of retries exceeded. (50/50)" when polling exhausted without task completion. ApiError — if getAppTask() returns an API error during polling. RetryError — if all Algolia hosts unreachable during polling.
  Required handlingCaller MUST wrap in try/catch. Handle both the timeout Error and API errors: try { await client.waitForAppTask({ taskID: response.taskID }); } catch (error) { if (error.message?.includes('maximum number of retries')) { console.error('App task timed out — check Algolia dashboard:', taskID); } else if (error instanceof ApiError) { console.error('API error while waiting for task:', error.status); } throw error; } To extend the timeout, pass maxRetries or a custom timeout function: waitForAppTask({ taskID, maxRetries: 100 })
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• saveObjectsWithTransformation · saveobjectswithtransformation-missing-region

  error
  WhensaveObjectsWithTransformation() called when the Algoliasearch client was initialized WITHOUT the transformation.region option. This is a configuration error — the client must be initialized as: algoliasearch(appId, apiKey, { transformation: { region: 'eu' } }) Calling saveObjectsWithTransformation() on a client without transformation.region throws synchronously (before any network request). This is distinct from the normal SearchClient — only the full Algoliasearch client has this method.
  ThrowsError (native, synchronous) — "`transformation.region` must be provided at client instantiation before calling this method." or "`region` must be provided when leveraging the transformation pipeline".
  Required handlingEnsure the Algoliasearch client is initialized with transformation.region before calling this method. Wrap in try/catch to handle both configuration errors and Ingestion API (WatchResponse) errors from the pipeline: const client = algoliasearch(appId, apiKey, { transformation: { region: 'eu' } }); try { await client.saveObjectsWithTransformation({ indexName, objects }); } catch (error) { console.error('Transformation pipeline error:', error.message); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]algolia.com/doc/api-clienthttps://www.algolia.com/doc/api-client/advanced/handling-errors/
2. [2]algolia.com/doc/api-referencehttps://www.algolia.com/doc/api-reference/api-methods/partial-update-objects/
3. [3]algolia.com/doc/api-referencehttps://www.algolia.com/doc/api-reference/api-methods/clear-index/
4. [4]algolia.com/doc/api-referencehttps://www.algolia.com/doc/api-reference/api-methods/search-for-facet-values/
5. [5]algolia.com/doc/api-referencehttps://www.algolia.com/doc/api-reference/api-methods/delete-by/
6. [6]algolia.com/doc/rest-apihttps://www.algolia.com/doc/rest-api/search/partial-update-object
7. [7]algolia.com/doc/rest-apihttps://www.algolia.com/doc/rest-api/search/add-or-update-object
8. [8]algolia.com/doc/librarieshttps://www.algolia.com/doc/libraries/javascript/v5/methods/search/
9. [9]algolia.com/doc/guideshttps://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors/push/