Troubleshooting the Revised API and MCP server

Each heading below is a symptom. Find yours, read the cause, apply the fix. For every status code and error code in one table, see Errors.

Authentication

Every request returns 401 unauthorized

Something about the key did not resolve. Missing, malformed, unknown and revoked keys all return the same 401, deliberately.

• Send exactly Authorization: Bearer rvd_<prefix>_<secret> — one space, one token.
• Check nothing trimmed or wrapped the secret when you copied it.
• Check the key is still live on getrevised.com/account.

Do not retry the same key in a loop: failed authentications are counted per client IP, and past that budget you get 429 before any lookup. See Authentication.

Missing names and missing rows

domain is null

The name is withheld, for one of two reasons the field cannot distinguish:

1. Your plan has a monthly reveal ceiling and you have not revealed this listing. Reveal it with POST /api/v1/domains/{id}/reveal, or stick to tier=open, whose names always arrive.
2. Another account holds the listing. hold_state is "other" and hold_expires_at says when it frees up. No plan is exempt.

Render mask_hint in the meantime, and test name_disclosed rather than whether a mask is present. See Masked names.

A filter returns far fewer rows than expected

Three usual causes:

• A minimum filter dropped the unknowns. ageMin, citabilityMin and checkedDays exclude rows with no value rather than ranking them low. ageMin=1 means “at least a year old and the age is known”. Sort locally instead of filtering, and check metrics_missing.
• category reaches about a third of the directory. Most listings carry no category, and no category value returns them. See Category codes.
• You changed a filter or sort mid-run. A cursor continues from its position under the new query and silently skips everything behind it. Keep the query identical on every page.

Searching for a domain name finds nothing

By design. q covers the masked hint, keyword tags, category and blurb — never the real name, on any plan and any tier. Revised does not confirm whether a given name is in the directory. If you have a listing id, use GET /api/v1/domains/{id}.

404 on an id you know exists

• The listing is newer than your plan’s delay. New listings are hidden for 7 days on Free and 1 day on Pro. See Plans and limits.
• The listing has left the directory, usually because someone registered the name. Drop the id.
• The id was lower-cased somewhere. Ids are case-sensitive: HSBQyXkl and hsbqyxkl are different. Store them verbatim, in a case-sensitive column.

Refused requests

400 on rd=<10 or rd=250+

rd takes band ids, not the values rows report: lt10, 10-50, 50-100, 100-250, 250plus. Only the two ends differ, which is why this fails exactly where you are most likely to want it. See Filters.

400 on ?limit=

An empty limit is refused on purpose, because it is what ?limit=${n} sends for an undefined n. Out-of-range numbers are clamped (above 250 reads as 250), but a non-number is an error.

400 on a category code

Unknown codes are refused rather than answered with an empty page. The codes are Revised’s own — there is no marketing or software. Use one from the published list, or list_categories over MCP.

402 upgrade_required

Read reveal_code or hold_code first:

What you called	Code	Fix
GET /api/v1/domains?since=…	none	The change feed is Business only. Page with cursor instead.
Reveal	QUOTA_EXHAUSTED	Wait for resets_at, the first of next month (UTC).
Reveal a featured listing on Free	FEATURED_REQUIRES_PRO	Filter with tier=open, or upgrade.
Hold on Free	HOLDS_REQUIRE_PRO	Holds start on Pro.

A hold is refused with REVEAL_REQUIRED on Business

A hold needs a reveal on record for the same listing and account. On a plan with no reveal ceiling every name arrives disclosed, but seeing a name is not the same as having revealed it. Call reveal first — it is free on Business — then hold.

429 rate_limited

Sleep for Retry-After seconds, then retry. Two things commonly cause it:

• MCP and REST share one counter per key. An agent session and a script on the same key draw from the same window.
• A tight paging loop. Use limit=250 and a short pause between pages. At 250 rows a page, Free’s 20 requests a minute is still 5,000 listings a minute.

See Rate limits.

X-RateLimit-Remaining did not go down

The window is fixed to the wall-clock minute, not sliding. If the minute turned over between two requests, the counter reset. Pace against X-RateLimit-Reset.

Data that looks wrong

A name listed as available is already registered

availability_checked_at is when Revised last confirmed the name was unregistered, not a live check. A name can be registered minutes after the stamp. Filter with checkedDays for fresher stamps, and always confirm at a registrar.

Every metric is a range, not a number

Deliberate. Metrics are published as bands at every tier. Flatten to a midpoint to sort, keep the band to display. See Metrics explained.

The change feed did not re-deliver a row whose hold changed

Taking, extending or ending a hold does not move updated_at, so since does not see it. Read the listing directly, or GET /api/v1/holds for your own.

MCP

The assistant answers without calling any tool

The server is not connected. Check the client’s MCP list — claude mcp list, codex mcp list, or Settings → MCP in Cursor — then ask “What plan am I on with Revised?”, which should call whoami.

401 with no browser prompt

The client does not implement OAuth discovery. Configure it with an API key instead, sent as Authorization: Bearer rvd_.... See Other clients.

405 Method Not Allowed

The client sent GET or DELETE, which means it is trying to open an SSE session. The server speaks Streamable HTTP over POST only; choose the HTTP transport.

403 with insufficient_scope

The sign-in granted less than the server needs. Disconnect and connect again, and accept the consent screen. See MCP authentication.

Still stuck

Email support@getrevised.com with the request, the full response body and the time you sent it. Include your key’s prefix — the part after rvd_ and before the next underscore — never the secret.