Skip to main content

Idempotency, retries, and errors

Idempotency​

  • Reuse the same idempotency key for a retry of the same logical API request.
  • Use a new key when the logical content or operation changes.
  • Keep stable external product/event identities across retries.
  • Do not use a future updated_at; monotonic guards intentionally reject older source truth.

Retry policy​

Retry network failures, 429, and 503 with exponential backoff, full jitter, and a bounded total window. Honor Retry-After when present. Do not automatically retry schema/validation/authentication errors until corrected.

Asynchronous results​

Product/index acceptance and webhook 202 mean durable admission, not immediate search visibility. Poll the relevant run/status/capabilities projection using bounded intervals.

Error handling​

Log the public error code, request/trace id, operation id, and HTTP status. Never log credentials, signatures, raw payloads, source URLs, or customer data. Show operators a concrete next action when the response includes one.