Idempotent Requests

Idempotency lets clients safely retry POST requests without performing the same operation twice. When a client includes the ⁠IdempotencyKey⁠ header with a POST, the server associates that key with the first request’s result and returns the same result to any subsequent retries using the same key and identical parameters (same method, url, and body).

Use cases

Network timeouts or transient errors: Retry the same POST with the same ⁠IdempotencyKey⁠ to receive the original result.
Client crashes between request and response: Resend the request using the same key to avoid duplicate creations or updates.

How it works

Client generates a unique key per operation (for example, a V4 UUID or other high‑entropy random string). Keys can be up to 255 characters.
Client sends a request with:
- All request parameters/body exactly as intended
- ⁠IdempotencyKey⁠ header set to the generated key
Sivo processes the first request, then stores the resulting HTTP status and response body under the provided key.
Subsequent POST requests with the same ⁠IdempotencyKey⁠ and identical parameters return the original status and body.

Parameter matching

The idempotency layer compares the incoming parameters (body, url, and method) to the first request for that key.
If parameters differ, the request is rejected to prevent accidental reuse. The existing idempotency entry is deleted to prevent situations where clients might get stuck. The request can be retried with the same (or different) ⁠IdempotencyKey⁠ for a distinct operation.

Key lifetime and reuse

Keys are be pruned after 24 hours. If a pruned key is reused, the server treats it as a new request and processes it again.
To avoid collisions:
- Generate keys with sufficient entropy.
- Do not reuse keys across different operations.

Validation and concurrency

Results are saved only after endpoint execution begins.
If a request is retried while the original request is executing it will fail to avoid duplicate execution.

Error behavior

Failed requests are not cached. If they are retried the application will attempt to execute them again.

Guidelines for developers

Generate one ⁠IdempotencyKey⁠ per logical operation (for example, “create payment,” “update profile”).
Persist the key until you receive a final response or until your retry window ends.
Retries should reuse the same key and identical parameters.
Do not share keys between unrelated operations.

Examples

Create a payment (retry‑safe)

POST /sellers/seller_id/invoices
Headers:IdempotencyKey: 8f0f6e3d-3b2a-4c2d-9ad9-7f8a1b9c77b1

Body:{
  "amount": 2500,
  "currency": "USD",
  "source": "tok_abc123"
}

First attempt: Returns 200 with the created payment.
Retry after timeout: Returns the same 200 response and body.

Parameter mismatch (payload validation error)

Second request:IdempotencyKey: 8f0f6e3d-3b2a-4c2d-9ad9-7f8a1b9c77b1

Body:{
  "amount": 3000,            // changed
  "currency": "USD",
  "source": "tok_abc123"
}

Result: An error is returned indicating that the payload does not match the stored request. The stored record is deleted to prevent client applications from being stuck. A second attempt will succeed.

Key reuse after pruning

If you reuse a key after it has been pruned (≥ 24 hours old), the server processes the request as new and stores the fresh result under that key.

Recommendations

Prefer UUIDv4 for keys; any random, high‑entropy string is acceptable.
Treat the key as sensitive data. Do not expose it to untrusted clients unless required by your architecture.
Use one key per operation attempt; never use the same key for multiple different operations.

FAQ

Do retries return the same headers? Retries return the same HTTP status and response body; some headers (for example, request identifiers) may differ per attempt.
How long are keys kept? Keys are eligible for pruning after at least 24 hours.