Problem Statement
Error Responses documents WHEN to retry (429/500/503 + backoff) but never whether a retry is SAFE. Because ingestion is async (202 Accepted), a timed-out ingest that is actually succeeding, retried without a stable id, silently duplicates the document or memory. Separately, re-ingesting to fix a failed attempt replaces the WHOLE source under upsert - a partial re-ingest drops fields. Neither footgun is documented.
Proposed Solution
Add essentials/v2/idempotency-and-retries: which operations are idempotent by default; the async-202 duplicate trap and the stable-id + upsert fix; upsert-replaces-whole-source; retry-safe create (409 already exists) and delete (404 already gone); and a safe-retry checklist. Grounded in the existing ingest/status/error-responses contracts.
Alternatives Considered
- Adding a note to Error Responses: that page owns retry TIMING; idempotency is a distinct, larger topic deserving its own page.
Additional Context
Submitted for the Mintlify x HydraDB documentation hackathon.
Problem Statement
Error Responses documents WHEN to retry (429/500/503 + backoff) but never whether a retry is SAFE. Because ingestion is async (202 Accepted), a timed-out ingest that is actually succeeding, retried without a stable id, silently duplicates the document or memory. Separately, re-ingesting to fix a failed attempt replaces the WHOLE source under upsert - a partial re-ingest drops fields. Neither footgun is documented.
Proposed Solution
Add essentials/v2/idempotency-and-retries: which operations are idempotent by default; the async-202 duplicate trap and the stable-id + upsert fix; upsert-replaces-whole-source; retry-safe create (409 already exists) and delete (404 already gone); and a safe-retry checklist. Grounded in the existing ingest/status/error-responses contracts.
Alternatives Considered
Additional Context
Submitted for the Mintlify x HydraDB documentation hackathon.