Idempotency
The Idempotency-Key header and idempotency_key field, 24-hour retention, same/different body behavior, the in-progress request lease, which operations support it, and automatic keys in the SDKs.
To retry safely after a network error or timeout, use an idempotency key on write operations: a request repeated with the same key does not create a second resource; the original response is returned.
Usage
POST /v1/notifications HTTP/1.1
Authorization: Bearer hs_live_…
Idempotency-Key: order-1001
Content-Type: application/json
{ "app_id": "app_…", "target": { "include_external_ids": ["user_42"] }, "contents": { "tr": "…" } }- The header is the preferred way; for compatibility with legacy providers, the
idempotency_keyfield in the body is also accepted. If both are given and differ, you get400 HS_VALIDATION_ERROR. - A key is at most 255 characters and is unique per app; use a business-meaningful value such as an order number, or a UUID.
- Which operations support it is shown in the reference parameter table as the
Idempotency-Keyheader: most notablyPOST /v1/notificationsandPOST /v1/apps/{app_id}/users(upsert).
Behavior
| Situation | Response |
|---|---|
| New key | The request is processed; the response and a body digest (SHA-256) are stored for 24 hours |
| Same key + same body (within 24 hours) | The stored response is returned as-is (same id, same status code); no new message is created |
| Same key + different body | 409 HS_IDEMPOTENCY_CONFLICT |
| Same key, first request still processing | 409 HS_IDEMPOTENCY_IN_PROGRESS — retry the same request shortly |
| Process crashed during the first request | The record is released after a 2-minute lease; a retry takes over |
| After 24 hours | The key can be reused (new operation) |
Concurrent requests with the same key are serialized at the database level (single winner); the loser of the race receives 409 HS_IDEMPOTENCY_IN_PROGRESS.
In the SDKs
With autoIdempotencyKey (on by default), the server SDKs generate a UUID automatically for idempotent operations when you don't pass a key, and use the same key on retries; so a retry after 429/5xx never produces a duplicate message. Explicit key: Node hs.notifications.create(body, { idempotencyKey }) or idempotency_key in the body; Python/Ruby idempotency_key=; Go pushizo.WithIdempotencyKey("…"); Java RequestOptions.builder().idempotencyKey("…"); .NET new RequestOptions { IdempotencyKey = "…" }; PHP create([...,'idempotency_key' => '…']).
Other write operations
For operations that don't support idempotency keys, rely on natural idempotency: user/alias/subscription write endpoints have external_id/token-based upsert behavior; campaign state transitions (send, pause, cancel) return the current state or 409 HS_CONFLICT when repeated; on the webhook receiver side, deduplicate using Pushizo-Event-Id.
Rate limits and quotas
Plan-based API request rate (api_rps), X-RateLimit headers, 429 and Retry-After behavior, per-endpoint limits, nginx IP limits, plan quotas and SDK retry rules.
Pagination, filtering and sorting
Cursor-based listing (limit, cursor, next_cursor, has_more), cursor format and validity, filter[...] and sort parameters, and helpers in the SDKs for iterating over all pages.