Queek docs

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:

SituationResult
Same key, same bodyThe stored status and JSON body are replayed with Idempotent-Replayed: true for 24 hours.
Same key, different body409 idempotency_key_reuse. The key already means something else.
Same key, two requests in flightThe 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 higherThe response is not stored. A retry with the same key runs the request again.
24 hours laterThe 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.

CeilingValueScope
Shared bucket180 requests per minutePer key and IP
Plan quotafree 60 · social_media 120 · starter 120 · growth 240 · scale 1,200 · enterprise 2,400 per minutePer 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.

On this page