Errors & limits

The response envelope

kwery distinguishes validation problems from infrastructure problems.

Validation problems are returned with HTTP 200 and an "error": true body. Always check the error field before consuming a response:
```
{ "error": true, "message": "country not supported by source" }
```

Infrastructure problems use standard HTTP status codes:

Status	Meaning
`401`	Missing or invalid credentials.
`402`	Out of credits — free tier at zero balance, a `cap_stop` spending cap reached, or overage mode `off` with included credits spent. See Pricing.
`403`	Authenticated, but not allowed (e.g. accessing another account's job).
`5xx`	Transient server-side problem. Safe to retry — a submission that fails never consumes credits.

Common validation messages include unknown source (the source value is not one of the identifiers in the sources table — display names such as google_shopping are not accepted), not subscribed to source (a real source, but your account is not enabled for that country), country not supported by source, parameter missing, parameter value invalid, and job not found. Per-value problems (e.g. a bad GTIN checksum) are reported on that value's result as success: false with a reason, rather than failing the whole job.

What consumes credits

Credits are billed per result, never per HTTP call:

Outcome	Billed?
Freshly crawled result with `success: true` (`served_from: "live"`)	Yes
Result re-served from cache within `max_age` (`served_from: "cache"`)	No — free
"Not found" (`success: true`, `reason: "not found"`) — freshly crawled	Yes
"Not found" re-served from the not-found cache within `not_found_max_age` (`served_from: "cache"`)	No — free
Crawl failure (`source currently unavailable`, `timeout`, lost)	No
Invalid input value (`parameter_invalid`)	No
Any request rejected with `4xx`/`5xx` or a validation error	No

Per-result fields

Each result in a download or stream delivery has:

Field	Description
`key`	The `key:value` this result is for.
`success`	`true` if the lookup completed (including a clean "not found").
`reason`	Present when relevant — e.g. `not found`.
`content`	The parsed product/offer data (source-specific — see Sources).
`served_from`	`live` — at least one fetch was made for this job; `cache` — re-served from a cached observation, no fetch.
`observed_at`	When the data was observed (ISO 8601, UTC): the last fetch for `live`, the cached observation's date for `cache` (`null` when unknown).
`trust`	Confidence score: `score`, `components{}`, `flagged_offers[]` — see Confidence score. Absent on failed lookups.

"Not found" versus "no offers". reason: "not found" means the marketplace does not know the product you asked for. A product that exists but has no purchasable offer at the moment (sold out, seller delisted, in-store only) is a normal success: true result with its identity fields, offers: [], offers_count: 0, buybox: null and null prices — and it is billed as a lookup, because the marketplace was queried and answered. Both carry a trust object. | meta | Provenance block (meta.crawls[]) — only when the job was submitted with include_meta: true; see Audit & provenance. | | index | 0-based position in the submitted values[] (stream results). |

Limits

Limit	Value
Batch values per job	1 000
Stream values per job	100 000
Stream results per polling page	1 000 (`limit`)
Result retention	72 hours

Results are retained for 72 hours after completion; download or consume them within that window.

Rate limiting

There is no fixed per-account request-rate limit — we do not throttle you by request volume, and there is no per-second or per-minute quota to design around.

What can stop a burst is credits. If you use up your plan credits, or reach an optional daily credit cap you set yourself, submission returns 402 with a machine-readable code your client can branch on:

`code`	Meaning
`depleted`	Plan credits (plus rollover) are used up.
`daily_quota`	Your own daily credit cap for today is reached; it lifts at the next local midnight.
`budget_cap`	Overage mode `cap_stop` and the spending cap is reached.
`overage_payment_failed`	New overage is paused because a payment failed; included credits keep working.

See Pricing for the credit model and Account management for setting a daily cap. If you plan a very large or sustained workload, talk to us first so we can size capacity.