Idempotency
Network glitches happen. If your request times out you don't always know whether the server processed it or not. Set an Idempotency-Key header on POST/PATCH requests and it's safe to retry: we return the cached response instead of re-executing.
How it works
- Generate a UUID (or any unique string ≤ 128 chars) per intended operation. Reuse the SAME key on every retry of that operation.
- Send it as
Idempotency-Key: <value>. - First request: runs normally, response cached for 24h.
- Retry within 24h with same key + same body: returns the cached response with header
Idempotency-Replay: true. - Retry with same key but different body: returns 409 CONFLICT so you notice the bug.
Example
curl https://app.staffifyai.com/api/workspace/v1/contacts \
-X POST \
-H "Authorization: Bearer sfy_wsp_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: c47b5c2a-4f9a-4b34-9c12-e0d7ec5c40b8" \
-d '{
"first_name": "Jan",
"email": "[email protected]"
}'Which endpoints support it
All POST and PATCH endpoints on /api/workspace/v1/*. GET requests are already idempotent (no side-effects) so the header is ignored there; DELETE isn't supported. see the Errors page for the no-delete rule.
Limits
- Max 128 characters per Idempotency-Key.
- Cache TTL is 24 hours.
- Max 10,000 unique keys per API key per 24h. Reuse keys for the same operation instead of generating a new one per retry.
Body-mismatch error
HTTP 409 Conflict
{
"error": {
"type": "invalid_request_error",
"code": "IDEMPOTENCY_KEY_CONFLICT",
"message": "This Idempotency-Key was used before with a different request body. Use a new key or match the previous request."
}
}Best practice
Store the Idempotency-Key alongside the operation in your database before firing the request. On retry, read it back and reuse. that way even a process crash between generation and send is safe.