Idempotency & rate limits
Retry any write safely with Idempotency-Key, and the per-key quota shared with the Headless API.
Idempotency-Key
Every write on this API lists Idempotency-Key as a parameter in the
reference. Send a fresh random key per
logical request and retry with the same key on a network failure, and the
second request cannot execute twice.
curl -X POST https://api.usequeek.com/api/v1/merchant/inventory/adjustments \
-H "X-Client-Key: sk_live_..." \
-H "Idempotency-Key: 7d3c4c1a-2c50-4c0f-8f0f-3a4d1a2b9c77" \
-H "Content-Type: application/json" \
-d '{ "product_ids": ["the-id-from-a-listing"], "quantity_change": -2, "type": "adjustment", "reason": "weekly stocktake" }'The contract:
| Situation | Result |
|---|---|
| Same key, same body | The stored status and JSON body are replayed with Idempotent-Replayed: true for 24 hours. |
| Same key, different body | 409 idempotency_key_reuse. The key already means something else. |
| Same key, two requests in flight | The second waits up to 15s for the first to finish, then replays its response. If it is still running, Queek returns 409 idempotency_key_in_progress; retry with the same key. |
The response status is 400 or higher | The response is not stored. A retry with the same key runs the request again. |
| 24 hours later | The stored response has expired; the same key starts a new request. |
The slot is store + caller + METHOD:path + key, and the caller is the
Merchant API key itself — two keys of one store never replay each other's
writes. The body is checked against the stored request fingerprint, not used
as part of the slot. GET requests ignore this header. Always send a key on
writes: without one the request runs without idempotency protection.
Rate limits
Two ceilings apply to a private key. Exceeding either answers 429 too_many_requests with a
Retry-After header.
| Ceiling | Value | Scope |
|---|---|---|
| Shared bucket | 180 requests per minute | Per key and IP |
| Plan quota | free 60 · social_media 120 · starter 120 · growth 240 · scale 1,200 · enterprise 2,400 per minute | Per private key, from the store's plan |
The plan quota is shared across the Merchant and Headless APIs: calls with the same key draw
from one allowance. An app's installation token is a private key for this purpose and follows
the same rule. Successful responses carry X-RateLimit-Limit and X-RateLimit-Remaining.
On a 429, wait the Retry-After interval, then retry. Add jitter if several workers share a
key, so they do not return in the same second. Sending a unique Idempotency-Key per write
makes that retry safe.
Invalid or refused credentials have a separate per-address limit. Valid credentials are never charged to that bucket.
Choosing a plan quota
Spend the allowance on changes, not on scans. Read with limit=100, walk with updated_after
instead of rescanning the whole list, and use webhooks instead of polling. See
Building safe integrations.