Idempotency Planned
Network hiccups happen. A retry should never charge a customer twice, add duplicate points, or issue two redemptions for the same invoice. TheIdempotency-Key header makes retries safe.
This mechanism is built but not yet attached to a live endpoint. It is reserved for the upcoming synchronous write endpoints — redemption validate/confirm/void and refund check. The one endpoint you call today, POST /api/partner/v1/events, is already safe to retry: it deduplicates on the eventId in the body (seeEvent types), so it needs noIdempotency-Key. This page documents how the header will behave once those endpoints ship.
How it works
- You send a request with a unique
Idempotency-Keyheader. - Quroosh processes it, then caches the full response (status code + body) keyed by
(apiKeyId, idempotencyKey)for 24 hours. - Any retry with the same key returns the cached response immediately — the business logic runs exactly once.
Which responses are cached
| Status class | Cached? | Rationale |
|---|---|---|
2xx | Yes | Success — retrying must not repeat the effect. |
4xx | Yes | Client error — retrying without changes will fail identically. |
422 | Yes | Validation error — same input, same failure. |
5xx | No | Server error — you should retry, and the retry may succeed. |
A good idempotency key is unique per business operation, not per HTTP attempt. For invoice-earned events, use the invoice id (INV-2026-000123) or the event id (a ULID/UUID generated once at the source system). Random-per-attempt keys defeat the purpose.
Key rules
- Header name:
Idempotency-Key. - Length: 1–255 characters.
- Scope: per API key. Two partners using the same key value do not collide — the cache is keyed by
(apiKeyId, idempotencyKey). - TTL: 24 hours from the first request. After that the key is free to reuse.
A reused key replays the cached response as-is — even if you send a different body. Always use a fresh key for a new operation; reusing a key across two different requests returns the first one's result, not the second's.
Which endpoints will require it
The upcoming synchronous write endpoints — redemption validate/confirm/void and refund check — will require the header; a request without it is rejected with 400 MISSING_IDEMPOTENCY_KEY. The event ingest endpoint does not use it (it dedups on eventId).