Idempotent requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when a network error occurs and you're unsure whether the request reached the server you can retry with the same idempotency key and either receive the original response or have the operation execute exactly once.

Usage

To make a request idempotent, include the idempotency-key header:

curl -X POST https://ingest.spektr.com/data \
  -H "Authorization: Bearer <api-key>" \
  -H "idempotency-key: 7c4a8d09-ca37-4a7b-9b0d-1b2e3f4a5b6c" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

The key can be any string up to 255 characters. We recommend using V4 UUIDs or another source with enough entropy to avoid collisions.

Supported Endpoints

Idempotency keys are accepted on the following endpoints:

How It Works

1. The client generates an idempotency key and sends it in the idempotency-key header.
2. The server computes a fingerprint of the request (HTTP method, path, query parameters, and body) and atomically creates a record keyed by (idempotency-key, workspaceId).
3. If the request is new, it executes normally. The resulting status code and response body are stored alongside the key.
4. If the key has been seen before with the same request parameters, the stored response is replayed — no side effects are repeated. Replayed responses include the idempotent-replayed: true response header so you can distinguish them from original responses.
5. If the key has been seen before but with different parameters (method, path, query, or body), the request is rejected with 422 Unprocessable Entity to prevent accidental misuse.

Key Expiration

Idempotency keys are automatically pruned 24 hours after creation. After a key expires, sending the same key is treated as a new request.

Error Handling

Results are only stored after the endpoint executes successfully. If the request fails (e.g., a database error or an unhandled exception), the idempotency record is removed and the key can be reused on retry. Validation errors (400) are never stored you can retry these freely without a new key. If you send a request while a previous request with the same key is still being processed, the server responds with 409 Conflict rather than executing the operation twice.

Error Codes

Response Headers