{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Errors & Limits — kwery Docs","siteUrl":"https://docs.kwery.co","description":"kwery's error response envelope, HTTP status codes, and rate limits explained."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"errors--limits","__idx":0},"children":["Errors & limits"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-response-envelope","__idx":1},"children":["The response envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["kwery distinguishes ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["validation problems"]}," from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["infrastructure problems"]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Validation problems"]}," are returned with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP 200"]}," and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"error\": true"]}," body. Always"," ","check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," field before consuming a response:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{ \"error\": true, \"message\": \"country not supported by source\" }\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Infrastructure problems"]}," use standard HTTP status codes:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or invalid credentials."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["402"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Out of credits — free tier at zero balance, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cap_stop"]}," spending cap reached, or overage mode ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["off"]}," with included credits spent. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/pricing#overage"},"children":["Pricing"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authenticated, but not allowed (e.g. accessing another account's job)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transient server-side problem. Safe to retry — a submission that fails never consumes credits."]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common validation messages include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unknown source"]}," (the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}," value is not one of the"," ","identifiers in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/sources#sources"},"children":["sources table"]}," — display names such as"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["google_shopping"]}," are not accepted), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not subscribed to source"]}," (a real source, but your"," ","account is not enabled for that country), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country not supported by source"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parameter missing"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parameter value invalid"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["job not found"]},". Per-value problems (e.g. a bad"," ","GTIN checksum) are reported on that value's result as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success: false"]}," with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]},","," ","rather than failing the whole job."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-consumes-credits","__idx":2},"children":["What consumes credits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Credits are billed ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["per result"]},", never per HTTP call:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Outcome"},"children":["Outcome"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Billed?"},"children":["Billed?"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Freshly crawled result with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success: true"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["served_from: \"live\""]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Yes"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Result re-served from cache within ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max_age"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["served_from: \"cache\""]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No — free"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"Not found\" (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success: true"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason: \"not found\""]},") — freshly crawled"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Yes"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"Not found\" re-served from the not-found cache within ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_found_max_age"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["served_from: \"cache\""]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No — free"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Crawl failure (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source currently unavailable"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeout"]},", lost)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid input value (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parameter_invalid"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Any request rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4xx"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}," or a validation error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"per-result-fields","level":2,"__idx":3},"children":["Per-result fields "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each result in a download or stream delivery has:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key:value"]}," this result is for."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," if the lookup completed (including a clean \"not found\")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Present when relevant — e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not found"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The parsed product/offer data (source-specific — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/sources"},"children":["Sources"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["served_from"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["live"]}," — at least one fetch was made for this job; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cache"]}," — re-served from a cached observation, no fetch."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["observed_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When the data was observed (ISO 8601, UTC): the last fetch for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["live"]},", the cached observation's date for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cache"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," when unknown)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trust"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Confidence score: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["score"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components{}"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flagged_offers[]"]}," — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/trust"},"children":["Confidence score"]},". Absent on failed lookups."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["\"Not found\" versus \"no offers\"."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason: \"not found\""]}," means the marketplace does not"," ","know the product you asked for. A product that ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["exists"]}," but has no purchasable offer at the"," ","moment (sold out, seller delisted, in-store only) is a normal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success: true"]}," result with its"," ","identity fields, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offers: []"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offers_count: 0"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buybox: null"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," prices — and it"," ","is billed as a lookup, because the marketplace was queried and answered. Both carry a"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trust"]}," object."," ","| ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta"]}," | Provenance block (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta.crawls[]"]},") — only when the job was submitted with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["include_meta: true"]},"; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/audit-and-provenance"},"children":["Audit & provenance"]},". |"," ","| ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index"]}," | 0-based position in the submitted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["values[]"]}," (stream results). |"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"limits","__idx":4},"children":["Limits"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Limit"},"children":["Limit"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Batch values per job"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["1 000"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stream values per job"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["100 000"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stream results per polling page"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["1 000"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Result retention"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["72 hours"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Results are retained for 72 hours after completion; download or consume them within that"," ","window."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rate-limiting","__idx":5},"children":["Rate limiting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["What can stop a burst is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["credits"]},". If you use up your plan credits, or reach an optional"," ","daily credit cap you set yourself, submission returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["402"]}," with a machine-readable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," ","your client can branch on:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"code"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["depleted"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Plan credits (plus rollover) are used up."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["daily_quota"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your own daily credit cap for today is reached; it lifts at the next local midnight."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["budget_cap"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Overage mode ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cap_stop"]}," and the spending cap is reached."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["overage_payment_failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["New overage is paused because a payment failed; included credits keep working."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/pricing#overage"},"children":["Pricing"]}," for the credit model and"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/account-management"},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"see-also","__idx":6},"children":["See also"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication"},"children":["Authentication"]}," — the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not subscribed to source"]}," error and the"," ","subscription model."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/getting-started"},"children":["Getting started"]}," — the happy path."]}]}]},"headings":[{"value":"Errors & limits","id":"errors--limits","depth":1},{"value":"The response envelope","id":"the-response-envelope","depth":2},{"value":"What consumes credits","id":"what-consumes-credits","depth":3},{"value":"Per-result fields","id":"per-result-fields","depth":2},{"value":"Limits","id":"limits","depth":2},{"value":"Rate limiting","id":"rate-limiting","depth":2},{"value":"See also","id":"see-also","depth":2}],"frontmatter":{"seo":{"title":"Errors & Limits — kwery Docs","description":"kwery's error response envelope, HTTP status codes, and rate limits explained."}},"lastModified":"2026-10-02T18:22:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/errors-and-limits","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}