Home / Docs / Errors and limits

Errors and limits

Errors have the same body on REST and MCP: {"error": {"code", "message", ...details}}. REST sets the HTTP status in the table below, and MCP returns the same JSON as a tool result marked as an error.

Error codes

CodeHTTPWhen
invalid_input400A field is missing or invalid, or a slug, category, domain or cursor isn't recognised. issues lists each field and what's wrong with it.
unauthorized401A REST call to a paid or account operation had no key, or the key is invalid or revoked; a missing key also gets a signup_url. Over MCP, a request without a valid OAuth token or key gets HTTP 401 with a WWW-Authenticate header before any tool runs.
insufficient_credits402The call can't be covered by the balance, max_credits or the key's cap. See credits and billing.
account_suspended403The account is suspended. Reply to any WhichSitesUse email to sort it out.
not_found404No such endpoint.
rate_limited429Too many calls this minute. Includes retry_after_seconds and limit_per_minute, and REST also sends a Retry-After header.
internal500Something went wrong on our side.
billing_unavailable503Accounts can't be checked on the server right now.
snapshot_unavailable503The monthly dataset is loading. Try again in a few minutes.

Example

A count with a misspelled slug fails with HTTP 400. The error names the field and the slug, so an agent can look the slug up and try again:

{
  "error": {
    "code": "invalid_input",
    "message": "Unknown technology slug: hubspott. Call find_technologies to look up the right slug.",
    "issues": [
      {
        "field": "technologies",
        "message": "Unknown technology slug: hubspott. Call find_technologies to look up the right slug."
      }
    ],
    "unknown_technologies": ["hubspott"]
  }
}

Rate limits and trial limits

Limits count calls in one-minute windows. Signed-in calls count against the account, so every key and connected app on it shares one limit.

CallerCalls a minuteCounted per
No key (REST find_technologies and count_sites only)30IP address
Account that hasn't paid yet30Account
Account that has paid300Account

Until an account's first purchase, a call also returns at most 100 results, whatever limit says. Both limits lift as soon as the account pays for a plan or a top-up. The sign-up and sign-in forms send at most 10 emails an hour from one IP address.