Skip to main content
The Causeloop API supports idempotent mutations via the Idempotency-Key header. Sending the same key on a repeated request replays the original response instead of executing the operation again — making it safe to retry network errors and timeouts without worrying about duplicate creates or double-charges.

​
Which requests support idempotency

Idempotency keys are accepted on all mutating methods:
  • POST
  • PATCH
  • PUT
GET and DELETE requests are inherently idempotent and ignore the header.

​
How it works

  1. You attach an Idempotency-Key header with a unique value to a mutating request.
  2. The server processes the request normally and caches the response (for 2xx responses only) keyed by (Idempotency-Key, request path).
  3. If you send a second request with the same key and path, the server returns the cached response immediately — the handler is never called again.
  4. The replay response includes an Idempotency-Replayed: true header so you can distinguish a fresh response from a cached one.
Only successful (2xx) responses are cached. If the original request returned a 4xx or 5xx, the next request with the same key will be executed again.

​
The Idempotency-Key header

Idempotency-Key: <your_unique_key>
The key value is a string of your choice. Use a UUID or a similarly unique value. The key is scoped to the combination of key value and request path — the same key sent to a different endpoint is treated as a separate cache entry. Recommended format: UUIDs (v4) 
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

​
Cache lifetime

Idempotency responses are cached for 24 hours. After that window, a request with the same key will be processed as a new request. When Redis is configured (REDIS_URL), the cache is shared across all API replicas. Without Redis, the cache is in-process — a request hitting a different replica will be treated as new. For production deployments with multiple API instances, configure Redis to ensure consistent idempotency guarantees.

​
Example: safely creating an issue

Generate a unique key before the request, then reuse it on retries: 
IDEM_KEY=$(uuidgen)  # or python3 -c "import uuid; print(uuid.uuid4())"

curl -X POST https://api.causeloop.ai/v1/issues \
  -H "Authorization: Bearer $CAUSELOOP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEM_KEY" \
  -d '{"title": "Payment gateway timeout", "severity": "high"}'

​
Response headers

HeaderWhen presentDescription
Idempotency-ReplayedOn replayed responses onlyAlways true. Signals the response came from cache.

​
Key scoping

The cache key is (Idempotency-Key value, request path). This means:
  • POST /v1/issues with key abc-123 and POST /v1/patterns with key abc-123 are separate cache entries.
  • The same key reused across different paths does not cause cross-resource collisions.
Do not reuse the same key value for different logical operations on the same endpoint. If you create issue A with key abc-123, then later try to create issue B with the same key on POST /v1/issues, you will receive the cached response for issue A instead.