URL: /docs/troubleshooting --- title: Troubleshooting the Revised API and MCP server sidebarTitle: Troubleshooting description: Fixes for the problems people actually hit with the Revised API and MCP server — 401s, null domain names, filters that return too little, 404s on real ids, 402s, 429s and agents that will not connect. icon: life-buoy --- 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](/docs/api/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__` — 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](https://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](/docs/api/authentication#when-authentication-fails). ## 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](/docs/concepts#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](/docs/guides/finding-domains#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](/docs/api/plans-and-limits#new-listing-delay). - **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](/docs/api/filters#rd). ### `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](/docs/guides/finding-domains#category-codes), 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](/docs/api/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](/docs/metrics#why-ranges-instead-of-exact-numbers). ### 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](/docs/mcp/install/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](/docs/mcp/authentication#failures). ## Still stuck Email [support@getrevised.com](mailto: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.