Retries and Idempotency
Retry safely without producing duplicate events, feedback, or contradictory decisions.
Retry matrix
| Operation | Retry guidance | Stable key |
| --- | --- | --- |
| Assessment | Retry only transport failures and reconcile by transactionId | transactionId |
| Event ingestion | Retry 429, 5xx, and network failures with jittered backoff | idempotencyKey |
| Feedback | Retry network and 5xx failures | idempotencyKey |
Generate a fresh x-event-nonce and current timestamp for every ingestion HTTP attempt, while keeping the event idempotencyKey unchanged.
Backoff
Use exponential backoff with jitter, cap the delay, and honor Retry-After when present. Do not retry validation, authentication, permission, or inactive-subscription responses until their cause changes.
Ambiguous outcomes
If the client disconnects after sending a request, treat the result as unknown. Reconcile using your stable identifiers before applying a second business action. A duplicate ingest may briefly return 503 ASSESSMENT_PENDING; retry it shortly with the same idempotency key and a new nonce.