API reference
Errors
{
"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
| Status | code | |
|---|---|---|
| 400 | bad_json | The body isn't valid JSON |
| 400 | invalid_request | A query parameter can't be read, like a bad cursor |
| 401 | unauthorized | The key is missing, unknown or revoked |
| 403 | limit_reached | You have 100 active or paused watchers, or 10 from test keys. Delete some or let them end (Limits) |
| 404 | not_found | No such watcher, event or route, or it belongs to another account |
| 409 | watcher_finished | A matched or expired watcher can't be resumed. Make a new one |
| 409 | idempotency_conflict | You reused an Idempotency-Key with a different body |
| 422 | no_webhook | The watcher has no notify.webhook to send a test or resend to |
| 422 | see below | The body broke a rule below |
| 429 | rate_limited | You sent over 120 requests in a minute. Wait Retry-After seconds |
| 500 | internal | Something failed on our side |
Validation codes
Shape
code | |
|---|---|
invalid_request | A field is missing, misspelled or the wrong type. field says which |
value_missing | The op needs a value |
value_not_list | in and not_in need a list |
value_not_number | price, price_drop and quantity need a number, "$20" or "10%" |
value_not_date | Dates look like 2026-12-15 |
value_unknown | availability or release_status has a status we don't know. message lists the valid ones |
Target and sites
code | |
|---|---|
match_query_shape | url needs a full https:// link on a site in where.sites. sku needs an identifier, like a GTIN, style code or ASIN |
exact_needs_version | exact needs the version in the name, like "Vomero 13". Use line to follow every version |
version_needs_line | version conditions need match: line or category, since exact already fixes the version. A then can't use them either |
site_unknown | We can't read that site |
site_unavailable | We can't read that site right now, because it isn't connected yet or it blocks all automated requests. message says why |
site_cant_match | That site can't run this match mode. message lists the ones it can |
site_not_reviewed | We don't support that site yet (Sites) |
site_terms_not_accepted | The 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_learned | We couldn't learn how to read the page. message says why, and field is the where.sites entry |
recipe_input_missing | The page needs a value the watcher didn't give. message names it, like location.zip |
llm_budget_reached | Your account's monthly LLM budget is spent, so we can't learn new pages until next month |
recipe_dead | We already gave up on this page after 3 relearns found nothing. Preview the watcher to try learning it once more |
bad_steps | A browser step, locale, timezone, cookie or location can't be used. message says which |
steps_submit_refused | On 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_unsupported | None of your sites gives that field |
target_fixed | target can't be updated. Make a new watcher instead |
Conditions
code | |
|---|---|
compare_to_needs_numeric | compare_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_compare | A percentage needs compare_to |
window_needs_duration | compare_to: window needs window, like "10m" |
window_needs_compare | window only works with compare_to: window |
min_n_needs_n | require: min_n needs an n no bigger than the number of values listed |
over_needs_values | over 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_many | over takes at most 20 values |
same_seller_needs_sites | same: seller needs two or more sites, or a site with several sellers |
list_change_needs_items | added and removed read the whole list, so use field items |
items_needs_list_op | Field items takes op added or removed |
list_change_alone | added and removed already compare with the last run, so leave out compare_to, window and over |
judge_needs_rule | judge needs the rule as a sentence in value, up to 300 characters |
judge_alone | judge already compares with the last run, so leave out compare_to, window and over |
item_needs_judge | Field item (the whole result) only works with op judge |
judge_too_many | A watcher can have at most 3 judged conditions |
judge_unavailable | No 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_us | ZIPs are US only, so set country to US or leave it out |
radius_needs_zip | A radius needs a zip to measure from |
radius_unreadable | Write the radius like "25mi" or "40km" |
currency_unsupported | Only USD works for now |
start_at_unreadable | We can't read start_at as a date |
start_after_until | start_at has to be before until |
until_unreadable | until takes a date, "+30d", "after_first_match" or "never" |
until_in_past | until has already passed |
until_too_far | A watcher can run for at most a year |
burst_needs_date | A burst near a date needs a condition, attribute or site that gives that date |
burst_needs_time | A burst needs at or near, but not both |
burst_at_unreadable | burst.at needs a datetime, like 2026-11-07T10:00:00-05:00 |
burst_faster_than_every | burst.every has to be shorter than every |
Notify and follow-ups
code | |
|---|---|
webhook_channel_without_config | channels has webhook but there's no notify.webhook |
webhook_config_without_channel | notify.webhook is set but channels doesn't have webhook |
webhook_needs_https | Webhook URLs have to use https, unless you're testing with local webhooks |
channel_needs_session | API keys use the webhook channel. site is only for Snag's own apps |
confirm_not_supported | notify.confirm needs a condition that stays true across checks. added, removed, changed, judge and back_in_stock are true on one check only |
then_nested | A then can't hold another then |
then_needs_single_match | then 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_disallowed | robots.txt disallows the page, and this watcher didn't accept the site's terms |
recipe_missing | We haven't learned how to read this page yet. Preview the watcher or create it again |
recipe_learned | We learned how to read the page on this check |
recipe_learn_failed | We couldn't learn how to read the page |
recipe_nothing_here | The page has nothing like the target (a home page or an error page) |
recipe_broken | The recipe stopped finding its items. After 3 misses in a row we relearn the page |
selector_not_found | A 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_empty | The part of the page we read had no text |
platform_unknown | On 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_magento | The store isn't on that platform |
no_product_cards | The store page is on the right platform but has no products we could read |
listing_partly_read, variants_partly_read | We couldn't read some items or options |
list_truncated, range_truncated, range_capped | There were more results or days than one check reads, so we left out the rest |
time_zone_unknown | The site gave times without a time zone we could work out |
ticket_classes_unavailable | We read the Eventbrite event, but not its ticket classes |
csrf_token_missing | OpenTable didn't give us the token its availability call needs |
unexpected_answer | The site's API answered in a shape we don't know, so nothing was read |
empty_as_400, empty_as_404 | NHTSA or openFDA said "no results" with an error status |
api_key_refused | The 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_address | The 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_confirmation | It matched, and notify.confirm is waiting for more checks in a row before it fires |
usage_limit | Your 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_allowed | The page showed a captcha, and we only solve them on sites we've reviewed |
site_not_reviewed | We 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_results | The 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_refused | The open-data portal or USAspending refused the filter in attributes, like a bad where or an unknown agency name |
radius_checked_after_fetch | The dataset stores coordinates as text, so we only checked the newest rows we read against the radius |
ticket_types_not_read | We read the DICE event's price and status, but not its ticket types |
no_event_date | We couldn't read the Tito event's calendar file, so the results have no date |
list_empty | A page-change list that matched before matched nothing this time |
format_changed | The 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_registrable | The 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_tld | IANA lists no RDAP server for that ending (like .de or .io) |
impact_unknown | For 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_stale | The road work feed hasn't been updated in a long time |
hours_not_read | For CivicRec facilities, we read the day but not the hours |
time_zone_default | For SimplePractice, we picked the days in New York time because time_zone wasn't set |
price_missing | A rental unit has no rent, or a rent of $0 |
filings_not_found, officers_not_found | Companies House has no filings or no officers on record for the company. The company itself was read |
nothing_listed | Magic Eden has no listings and no floor. A mistyped symbol looks the same, so check the symbol |
seo_not_for_pdf, seo_not_for_list | seo: true reads a page's tags, so it does nothing on a PDF or a list |
summary_unavailable | summarize: true is set, but no LLM is connected or the summary failed. We try again at most once an hour |
step_failed | We couldn't do a browser step, because nothing matched it or it timed out. The detail names the step |
not_a_page | The link is a file download, not a page, so watch it without browser: true |
recipe_review_pending | Built-in support for this page is waiting on a terms review, so we don't read it with a recipe either |
recipe_input_missing | The recipe needs a value the watcher doesn't give, like location.zip |
recipe_llm_budget | The page needed relearning, but the LLM budget is spent |
recipe_dead | We gave up on the page after 3 relearns found nothing. The stored recipe still runs. Preview the watcher to try learning it once more |