Retry-After, polls with backoff, and preserves ready results when some candidates fail.
Request
search_id; it is the handle used for every later poll. Applications that require safe POST retries after a lost response can additionally send an optional Idempotency-Key header.
Poll
Consume results
completed_with_errors is not a total failure. Keep the ready profiles and decide whether each failed result warrants a new logical request.
Production checklist
- Use a key with
search:readand, when embedding profiles,profile:read. - Persist
search_idwith your job record. - Put a client-side deadline around polling, but do not start duplicate work when it expires.
- Honor
Retry-Afteron429responses. - Log the Search ID, terminal status, and failure codes.
- Set
include_profile: falsewhen a downstream worker only needs IDs.
