kwery sits between your systems and marketplaces that change daily. This page is the short list of practices that make an integration ride through bad days — ours, yours, and the marketplaces' — without waking anyone up.
Per the API change policy, new response fields, sources, and event types can appear at any time. Read the fields you need, ignore unknown fields, never depend on field order, and treat every field outside key / success / reason as optional — a source can stop exposing an attribute (that's the marketplace's doing, and trust completeness will tell you).
Validation problems return HTTP 200 with {"error": true, "message": …} — consuming a response without checking error is the single most common integration bug. See Errors & limits.
5xxand network-level failures — transient server-side or connection problems. Retry with exponential backoff and a finite attempt count; a submission that fails this way never consumes credits. (There is no per-account rate limit to back off from — see Errors & limits.)- Per-value
reason: "source currently unavailable"— a transient crawl failure (never billed): re-submit those values in a later job rather than instantly. - Don't retry validation errors (
parameter …),401/403, or402— they won't succeed until something changes on your side.
A job with 1 000 values can contain found products, not-founds, and transient failures side by side. Process results per value on success + reason; never treat a finished job as "all good" or one bad value as a failed batch.
Log the job id for every submission, and the reason plus (with include_meta) the crawl_id for anything odd. A support request with a job id and a crawl id gets answered in minutes; "yesterday some results looked wrong" doesn't.
Ack 2xx immediately, process async, de-duplicate on X-Kwery-Delivery-Id (retries can race a slow ack), and verify signatures against the raw body. Full walkthrough: Webhooks. If your endpoint goes down, deliveries are retried for ~43 minutes and then dead-lettered for replay — build the replay call into your recovery runbook.
Monitor request volume, retry rates, and credit consumption — a buggy loop shows up in your credit curve before it shows up anywhere else. The dashboard shows balance and daily usage, and we email you at 80% / 95% / depleted so a runaway integration never burns silently. Cap worst-case overage spend with the cap_stop overage mode.
Results are downloadable for 72 hours. Persist what you need on your side promptly — retention is a pickup window, not an archive.
- API change policy — what can change without notice, and what can't.
- Errors & limits — envelope, status codes, what consumes credits.
- Webhooks — signature verification, retries, replay.