Idempotency and retries

Idempotency prevents a business operation from running twice during retries. GoodVision write requests use a stable Idempotency-Key; repeating the same request does not create duplicate results.

After a network timeout, the server may already have completed the operation. Retain the original request content and key, then follow the recovery steps below.

Generate one key per logical operation

Generate an unpredictable key when the user begins an operation. Persist it with the local command record and reuse it for every retry of the exact same payload.

POST /v1/oem/subscriptions/sub_opaque/cancel HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Idempotency-Key: 9a87c940-69a6-4b86-bf20-bca5cabd66d7
Content-Type: application/json

{"cancel_mode":"end_of_period"}

Never reuse a key for a different payload. The service can return 409 Conflict when the key is already bound to another request fingerprint.

Recover after a timeout

1. Retry the exact payload with the original key.
2. Query the asynchronous operation when an operation_id is available.
3. Read the current resource state to determine whether the original command completed.
4. Generate a new key only when the user intentionally starts a new logical operation.

Do not switch keys after a timeout and accidentally duplicate an order, cancellation, payment, or refund operation.

Retry decisions

Condition	Caller action
Network error or timeout	Original key and payload with bounded exponential backoff
429	Respect Retry-After and add jitter
Contract-defined transient 5xx	Retry within bounds, then query operation or resource state
400 / 422	Correct input and submit a new operation
401 / 403	Fix authentication or authorization; do not retry unchanged
409	Read current state and resolve the version or idempotency conflict

Webhooks are idempotent too

Webhook delivery is at least once. Deduplicate with event_id and prevent older state from overwriting newer state with resource_version. A delivery_id identifies an attempt, not a business event.