Snag Watcher

API reference

Errors

JSON
{
  "error": { "code": "burst_needs_date", "message": "A burst near release_date needs something that gives that date: a release_date condition or attribute, or a site that reports it.", "field": "schedule.burst.near" },
  "errors": [{ "code": "burst_needs_date", "message": "...", "field": "schedule.burst.near" }]
}

error is the first problem. On a 422, errors lists all of them, so you can fix the request in one go. field is the path in your body. A 422 can also carry a suggestion, a corrected request you can check and send (Suggestions).

Status codes

Statuscode
400bad_jsonThe body isn't valid JSON
400invalid_requestA query parameter can't be read, like a bad cursor
401unauthorizedThe key is missing, unknown or revoked
403limit_reachedYou have 100 active or paused watchers, or 10 from test keys. Delete some or let them end (Limits)
404not_foundNo such watcher, event or route, or it belongs to another account
409watcher_finishedA matched or expired watcher can't be resumed. Make a new one
409idempotency_conflictYou reused an Idempotency-Key with a different body
422no_webhookThe watcher has no notify.webhook to send a test or resend to
422see belowThe body broke a rule below
429rate_limitedYou sent over 120 requests in a minute. Wait Retry-After seconds
500internalSomething failed on our side

Validation codes

Shape

code
invalid_requestA field is missing, misspelled or the wrong type. field says which
value_missingThe op needs a value
value_not_listin and not_in need a list
value_not_numberprice, price_drop and quantity need a number, "$20" or "10%"
value_not_dateDates look like 2026-12-15
value_unknownavailability or release_status has a status we don't know. message lists the valid ones

Target and sites

code
match_query_shapeurl needs a full https:// link on a site in where.sites. sku needs an identifier, like a GTIN, style code or ASIN
exact_needs_versionexact needs the version in the name, like "Vomero 13". Use line to follow every version
version_needs_lineversion conditions need match: line or category, since exact already fixes the version. A then can't use them either
site_unknownWe can't read that site
site_unavailableWe can't read that site right now, because it isn't connected yet or it blocks all automated requests. message says why
site_cant_matchThat site can't run this match mode. message lists the ones it can
site_not_reviewedWe don't support that site yet (Sites)
site_terms_not_acceptedThe site's robots.txt or terms restrict automated access. Set fetch.accept_site_terms to true if you're allowed to fetch it
recipe_not_learnedWe couldn't learn how to read the page. message says why, and field is the where.sites entry
recipe_input_missingThe page needs a value the watcher didn't give. message names it, like location.zip
llm_budget_reachedYour account's monthly LLM budget is spent, so we can't learn new pages until next month
recipe_deadWe already gave up on this page after 3 relearns found nothing. Preview the watcher to try learning it once more
bad_stepsA browser step, locale, timezone, cookie or location can't be used. message says which
steps_submit_refusedOn a site we haven't reviewed, a step would send a contact, sign-up, registration, subscription, checkout or application form, or post a form after filling more than one field. Search and lookup steps are fine. message says which step
field_unsupportedNone of your sites gives that field
target_fixedtarget can't be updated. Make a new watcher instead

Conditions

code
compare_to_needs_numericcompare_to only works on numbers (price, quantity or a numeric attribute), or on any field with op changed. You also get it if price_drop, price_change or price_move has no compare_to
percent_needs_compareA percentage needs compare_to
window_needs_durationcompare_to: window needs window, like "10m"
window_needs_comparewindow only works with compare_to: window
min_n_needs_nrequire: min_n needs an n no bigger than the number of values listed
over_needs_valuesover has nothing to go over. Sizes need a size list, dates a date range or a listing, and items match: line, category or listing
over_too_manyover takes at most 20 values
same_seller_needs_sitessame: seller needs two or more sites, or a site with several sellers
list_change_needs_itemsadded and removed read the whole list, so use field items
items_needs_list_opField items takes op added or removed
list_change_aloneadded and removed already compare with the last run, so leave out compare_to, window and over
judge_needs_rulejudge needs the rule as a sentence in value, up to 300 characters
judge_alonejudge already compares with the last run, so leave out compare_to, window and over
item_needs_judgeField item (the whole result) only works with op judge
judge_too_manyA watcher can have at most 3 judged conditions
judge_unavailableNo LLM is connected yet, so we can't check judged conditions. Use a field and op instead, like text_hash changed

Location and schedule

code
zip_needs_usZIPs are US only, so set country to US or leave it out
radius_needs_zipA radius needs a zip to measure from
radius_unreadableWrite the radius like "25mi" or "40km"
currency_unsupportedOnly USD works for now
start_at_unreadableWe can't read start_at as a date
start_after_untilstart_at has to be before until
until_unreadableuntil takes a date, "+30d", "after_first_match" or "never"
until_in_pastuntil has already passed
until_too_farA watcher can run for at most a year
burst_needs_dateA burst near a date needs a condition, attribute or site that gives that date
burst_needs_timeA burst needs at or near, but not both
burst_at_unreadableburst.at needs a datetime, like 2026-11-07T10:00:00-05:00
burst_faster_than_everyburst.every has to be shorter than every

Notify and follow-ups

code
webhook_channel_without_configchannels has webhook but there's no notify.webhook
webhook_config_without_channelnotify.webhook is set but channels doesn't have webhook
webhook_needs_httpsWebhook URLs have to use https, unless you're testing with local webhooks
channel_needs_sessionAPI keys use the webhook channel. site is only for Snag's own apps
confirm_not_supportednotify.confirm needs a condition that stays true across checks. added, removed, changed, judge and back_in_stock are true on one check only
then_nestedA then can't hold another then
then_needs_single_matchthen needs a watcher that stops at its first match, so set until: after_first_match or aggregate: first

Check issues

These aren't request errors. Each site in a run (List runs) has an issues list for anything worth knowing about how we read the page, even when the check went fine.

For sites we read through an API, a check is blocked when the site answers 429, a 403 with x-ratelimit-remaining: 0 (GitHub), a 400 or 403 whose body says it's a rate limit (like Stack Exchange's throttle_violation), or a bot-check page where we expected JSON (with a 403 or a 200). We take retryAfterSeconds from the Retry-After header, then the rate limit's reset time, then an "in N seconds" in the site's message. Where our built-in support asks for it (Jane App), a redirect away from the clinic's own address is not_found. We follow redirects one hop at a time, up to 5, and check robots.txt on each host.

The most common issues are:

Issue
robots_disallowedrobots.txt disallows the page, and this watcher didn't accept the site's terms
recipe_missingWe haven't learned how to read this page yet. Preview the watcher or create it again
recipe_learnedWe learned how to read the page on this check
recipe_learn_failedWe couldn't learn how to read the page
recipe_nothing_hereThe page has nothing like the target (a home page or an error page)
recipe_brokenThe recipe stopped finding its items. After 3 misses in a row we relearn the page
selector_not_foundA page-change selector or list matched nothing. On the first read, the check fails and the detail names up to three selectors that do match. After it has matched once, a miss is reported but the check is still ok
region_emptyThe part of the page we read had no text
platform_unknownOn a line or category watch, the store isn't on Shopify, WooCommerce, Squarespace, BigCommerce or Magento
not_shopify, not_woocommerce, not_squarespace, not_bigcommerce, not_magentoThe store isn't on that platform
no_product_cardsThe store page is on the right platform but has no products we could read
listing_partly_read, variants_partly_readWe couldn't read some items or options
list_truncated, range_truncated, range_cappedThere were more results or days than one check reads, so we left out the rest
time_zone_unknownThe site gave times without a time zone we could work out
ticket_classes_unavailableWe read the Eventbrite event, but not its ticket classes
csrf_token_missingOpenTable didn't give us the token its availability call needs
unexpected_answerThe site's API answered in a shape we don't know, so nothing was read
empty_as_400, empty_as_404NHTSA or openFDA said "no results" with an error status
api_key_refusedThe site refused our key for it, or answered 400 saying the key is invalid or missing (NCBI, Stack Exchange). The detail has the site's own message
private_addressThe address points to a private or local network (localhost, 10.x, 192.168.x, 169.254.169.254, *.railway.internal), which we don't fetch. Use a public address
awaiting_confirmationIt matched, and notify.confirm is waiting for more checks in a row before it fires
usage_limitYour account used up its daily browser runs with steps (200) or captcha solves (100). They reset at 00:00 UTC, and the detail gives the time. The check is failed, not blocked, so it doesn't count toward a blocked event
captcha_not_allowedThe page showed a captcha, and we only solve them on sites we've reviewed
site_not_reviewedWe don't read this site because it would write to someone else's account, a law restricts it, or we haven't built support for it yet
partial_data, partial_resultsThe site's answer covers only part of what it lists, like a menu missing its group classes or OSV's first page
query_refused, search_refusedThe open-data portal or USAspending refused the filter in attributes, like a bad where or an unknown agency name
radius_checked_after_fetchThe dataset stores coordinates as text, so we only checked the newest rows we read against the radius
ticket_types_not_readWe read the DICE event's price and status, but not its ticket types
no_event_dateWe couldn't read the Tito event's calendar file, so the results have no date
list_emptyA page-change list that matched before matched nothing this time
format_changedThe link gave a PDF last time and a web page now, or the other way round. The result keeps its key, so it shows up as a change
rdap_not_registrableThe name is under a registered domain (like www.example.com), so it can't be registered on its own. The detail names the domain to watch
rdap_unsupported_tldIANA lists no RDAP server for that ending (like .de or .io)
impact_unknownFor road work, closed_only is set but the feed marks every event's impact as unknown (WSDOT), so we can't pick out closures
feed_staleThe road work feed hasn't been updated in a long time
hours_not_readFor CivicRec facilities, we read the day but not the hours
time_zone_defaultFor SimplePractice, we picked the days in New York time because time_zone wasn't set
price_missingA rental unit has no rent, or a rent of $0
filings_not_found, officers_not_foundCompanies House has no filings or no officers on record for the company. The company itself was read
nothing_listedMagic Eden has no listings and no floor. A mistyped symbol looks the same, so check the symbol
seo_not_for_pdf, seo_not_for_listseo: true reads a page's tags, so it does nothing on a PDF or a list
summary_unavailablesummarize: true is set, but no LLM is connected or the summary failed. We try again at most once an hour
step_failedWe couldn't do a browser step, because nothing matched it or it timed out. The detail names the step
not_a_pageThe link is a file download, not a page, so watch it without browser: true
recipe_review_pendingBuilt-in support for this page is waiting on a terms review, so we don't read it with a recipe either
recipe_input_missingThe recipe needs a value the watcher doesn't give, like location.zip
recipe_llm_budgetThe page needed relearning, but the LLM budget is spent
recipe_deadWe gave up on the page after 3 relearns found nothing. The stored recipe still runs. Preview the watcher to try learning it once more