Idempotency

Send a unique Idempotency-Key header with each request:

Idempotency-Key: 4f8c2a8e-6b1d-4c6e-9a3f-2b7d1e0c9a55

• Same key and same body within 24 hours returns the original result, marked meta.replayed: true and the Idempotent-Replayed: true header, and you are charged once.
• Same key with a different body returns 409 idempotency_conflict.
• Same key while the first request is still running returns 409 idempotency_conflict with retryable: true. It never runs twice; retry shortly with the same key to get the result.
• A failed first attempt was not charged, so a retry with the same key and body runs again.
• After 24 hours the key expires and returns 409 idempotency_conflict; use a new one.

Generate a new key (a UUID is ideal) for each logical operation, and reuse it only when retrying that same operation.