IndexNow key and key file: rules, errors and how to test yours

IndexNow (an open "this page changed" notice that Bing and other participating engines accept; Google doesn't use it) only works once the key checks out, so a broken key file means your notices are refused. This page sets out the rules, which URLs a key file covers, the exact errors the endpoints returned when we broke each rule on October 17, 2026, a script to test your own file, and the hosting setups that break it.

What are the IndexNow key and key file rules?

The IndexNow key rules cover the key's format, the file's name and content, and where it lives. As of October 2026, the IndexNow documentation sets them out like this:

One wording quirk: the same sentence calls the key "hexadecimal characters" and then allows any letter. The endpoints follow the wider rule. When we sent ABCD-efgh-1234 (uppercase, lowercase and dashes) on October 17, 2026, both api.indexnow.org and Bing's endpoint accepted the format and moved on to look for the file; their error message describes the key as "alphanumeric characters". Our IndexNow guide covers the protocol itself, including how to generate a key.

Where can the key file live, and which URLs does it cover?

The key file can live at the root of your host, where it covers every URL on that host, or in a folder named with keyLocation, where it covers only URLs in that folder. The documentation's example: a key file at http://example.com/catalog/key12457EDd.txt "can include any URLs starting with http://example.com/catalog/ but cannot include URLs starting with http://example.com/help/".

Three rules follow, as of October 2026:

1. Same host only. The file must be on the host you submit for. The endpoints reject a keyLocation on another domain, so you can't serve the key from a CDN hostname.
2. One key file per subdomain. The IndexNow FAQ says "Each subdomain is treated as a separate host, which means you must create and manage individual key files for each one." www.example.com and blog.example.com need one each.
3. Changing the key is allowed. Replace the file and submit with the new key; the FAQ says engines "will automatically re-verify ownership when the updated key is detected during URL submission."

What do IndexNow key errors look like?

Key errors come back as a status code plus a short JSON message, and the message tells you which rule failed. We sent each mistake below to both https://api.indexnow.org/indexnow and https://www.bing.com/indexnow on October 17, 2026, for www.example.com, which we don't control, so nothing was submitted. Both endpoints returned the same codes and messages:

The documentation's response table lists 400 as "Invalid format" and 403 for a key that isn't valid, but in our tests a badly formed key returned 422, and 403 meant the key file couldn't be confirmed. So read the message, not just the code. A 202 means "URL received. IndexNow key validation pending", which is normal for a new key. A 200 is the good result, and the documentation is clear about its limits: "The HTTP 200 response code only indicates that the search engine has received your URL."

If you're fixing a key so Bing hears about your pages, it's worth knowing where Google stands on the same URLs: check which of your pages Google has indexed, free.

How do you test your key file before you submit?

You test a key file by checking the key's format, the file's location and scope, then fetching it and comparing the content with the key. This script does all three with Python's standard library; we wrote and ran it on October 17, 2026:

# check_indexnow_key.py: test an IndexNow key and key file before you submit anything.
# Usage: python3 check_indexnow_key.py <host> <key> [keyLocation] [url ...]
import re, sys, urllib.request, urllib.error
from urllib.parse import urlsplit

host, key = sys.argv[1].lower(), sys.argv[2]
key_location = sys.argv[3] if len(sys.argv) > 3 and sys.argv[3].startswith("http") else None
urls = sys.argv[4:] if key_location else sys.argv[3:]
ok = True
def report(passed, msg):
    global ok
    ok = ok and passed
    print(("PASS " if passed else "FAIL ") + msg)

# 1. Key format: 8-128 characters, a-z, A-Z, 0-9 and dashes only.
report(bool(re.fullmatch(r"[A-Za-z0-9-]{8,128}", key)), f"key format ({len(key)} characters)")

# 2. Where the file must be, and which URLs it covers.
location = key_location or f"https://{host}/{key}.txt"
loc = urlsplit(location)
report(loc.hostname == host, f"key file is on {host}: {location}")
folder = loc.path.rsplit("/", 1)[0] + "/"
for u in urls:
    p = urlsplit(u)
    report(p.hostname == host and p.path.startswith(folder), f"{u} is covered by a key file in {folder}")

# 3. The file must answer 200 on the same host and contain only the key.
class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, *a, **k): return None
try:
    r = urllib.request.build_opener(NoRedirect).open(urllib.request.Request(location, headers={"User-Agent": "indexnow-key-check/1.0"}), timeout=20)
    body = r.read(4096).decode("utf-8-sig", "replace")
    report(True, f"HTTP {r.status}, Content-Type: {r.headers.get('Content-Type')}")
    report(body.strip() == key, "file contains exactly the key" if body.strip() == key else f"file content doesn't match the key (starts {body[:40]!r})")
except urllib.error.HTTPError as e:
    where = f" -> {e.headers.get('Location')}" if 300 <= e.code < 400 else ""
    report(False, f"key file answered HTTP {e.code}{where}")
except Exception as e:
    report(False, f"key file not reachable: {e}")
print("Ready to submit" if ok else "Fix the FAIL lines before you submit")

Two runs from that day show what failures look like. First, a key we never hosted, checked against our own site and against a Wix site:

$ python3 check_indexnow_key.py freshlycited.com 0123456789abcdef0123456789abcdef
PASS key format (32 characters)
PASS key file is on freshlycited.com: https://freshlycited.com/0123456789abcdef0123456789abcdef.txt
FAIL key file answered HTTP 404
Fix the FAIL lines before you submit

$ python3 check_indexnow_key.py www.yorisbakery.com 0123456789abcdef0123456789abcdef
PASS key format (32 characters)
PASS key file is on www.yorisbakery.com: https://www.yorisbakery.com/0123456789abcdef0123456789abcdef.txt
FAIL key file answered HTTP 400
Fix the FAIL lines before you submit

Second, a key with an underscore and a keyLocation in a folder, with one URL inside it and one outside:

$ python3 check_indexnow_key.py www.example.com abcd_efgh1234
FAIL key format (13 characters)

$ python3 check_indexnow_key.py www.example.com 0123456789abcdef0123456789abcdef \
    https://www.example.com/catalog/0123456789abcdef0123456789abcdef.txt \
    https://www.example.com/catalog/mugs https://www.example.com/help/returns
PASS key format (32 characters)
PASS key file is on www.example.com: https://www.example.com/catalog/0123456789abcdef0123456789abcdef.txt
PASS https://www.example.com/catalog/mugs is covered by a key file in /catalog/
FAIL https://www.example.com/help/returns is covered by a key file in /catalog/

(We left the fetch lines out of these two runs, because example.com is a placeholder host.) The script doesn't follow redirects on purpose. The documentation doesn't say whether engines follow a redirected key file, so serve it directly from the URL you submit.

Which setups break an IndexNow key file?

Most broken key files come from the host serving something other than the plain file.

• A catch-all route that returns a web page. Single-page apps and some CMSs answer every path with HTML and a 200. The fetch looks successful, but the content isn't the key. Our React SEO guide shows a Vite app doing exactly this for unknown paths.
• A platform that can't host root files. Wix says it's "currently not possible" to add a root-level .txt file (Wix Help Center), and our test above got a 400 from a Wix site. Squarespace, Webflow and Shopify document no way to place one either; use the platform's own IndexNow support where it exists, as our Wix guide and Shopify guide explain.
• Plugins that serve the key virtually. SEOPress says it "serves the public verification URL through WordPress; it does not create a physical file on disk" (SEOPress). That works, until a cache or security rule intercepts .txt requests. Our WordPress IndexNow guide compares how each plugin handles it.
• Bot protection and firewalls. A rule that challenges unknown clients can block the engines' fetch while your browser loads the file fine. Test from outside your network, as the script does.
• Two plugins with two keys. Each sends its own key; keep one sender. The same guide covers spotting duplicates in Bing's IndexNow report.

If the file passes every check but submissions still fail, look at the message the endpoint returns; the table above maps each one to its cause. For submission steps, see submitting URLs to Bing.

Where does FreshlyCited fit?

FreshlyCited's main job is Google: it checks which of your URLs Google has indexed, pushes only the ones it hasn't and re-checks them on days 1, 3 and 7. IndexNow is a free bonus for sites you verify. FreshlyCited generates a 32-character key for you, and you host the file; it checks the file returns exactly the key (a web page or extra text fails), accepts a keyLocation only on the same host, re-checks the file once a day, and pauses Bing pings after two failed checks in a row. After that, every push of URLs on that site is also "Sent to Bing", with a per-site off switch. The recipe to verify a site for IndexNow walks through it. The free plan gives you 10 free links to try, then 100 free checks a month, with no card. Check my pages free.