Documentation Index
Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
The event ingestion endpoint (POST /events) does not support the
Idempotency-Key header. Instead, each event carries a client-defined
unique_id field which is enforced as a natural unique key — sending the same
unique_id again is silently deduplicated. Use unique_id to make event
ingestion safe to retry; do not rely on Idempotency-Key for that endpoint.
How it works
Include an Idempotency-Key header with a unique string value in your request.
If you send the same request with the same idempotency key within 24 hours,
the API returns the original response without re-executing the operation.
curl -X POST https://api.alguna.io/beta/invoices \
-H "Authorization: Bearer <API-KEY>" \
-H "Alguna-Version: 2026-04-01" \
-H "Idempotency-Key: ik_create_invoice_cust123_20260330" \
-d '{ "customer_id": "cust_abc123" }'
Key behaviors
| Scenario | Response |
|---|
| First request with key | Operation executes normally |
| Replay with same key + same params | Cached response returned (no side effects) |
| Replay with same key + different params | 422 error: key already used with different parameters |
| Concurrent request with same key | 409 error: request currently being processed |
| Request after key expires (24h) | Operation executes as new |
| Header | Description |
|---|
Idempotency-Key | Echo of the key you provided |
Idempotent-Replayed | true if this response was served from cache, false if freshly executed |
| Header | Description |
|---|
Transient-Error | true — the idempotency key has been released and you can safely retry with the same key |
Error handling
Idempotency keys interact with errors as follows:
- 2xx responses: Cached and replayed on retry
- 4xx responses (validation, not found, etc.): Cached and replayed — these represent deterministic outcomes
- 429 Too Many Requests: Not cached — the key is released so you can retry after the rate limit resets
- 5xx responses: Not cached — the key is released so you can retry the operation
Best practices
- Generate unique keys: Use UUIDs, ULIDs, or a combination of meaningful identifiers
(e.g.,
ik_create_invoice_{customer_id}_{timestamp})
- Scope keys to operations: Don’t reuse the same key across different endpoints
- Retry with the same key: If your request times out or you receive a 5xx error,
retry with the same idempotency key — the server guarantees at-most-once execution
- Don’t retry on 4xx: Client errors (400, 422, etc.) are deterministic and will
return the same error on replay
- Maximum 255 characters
- Must contain only printable ASCII characters
- We recommend prefixing with a short identifier:
ik_<your_unique_value>
Expiry
Idempotency keys expire after 24 hours. After expiry, the same key string can be
reused for a new operation.
Which endpoints support idempotency?
All mutating endpoints (POST, PATCH, DELETE) accept the Idempotency-Key header.
GET requests are naturally idempotent and do not support the header.
The event ingestion endpoint (POST /events) is the one exception — it uses
the per-event unique_id field as a natural unique key instead of the
Idempotency-Key header.
