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
| Code | HTTP | When |
|---|---|---|
| invalid_input | 400 | A 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. |
| unauthorized | 401 | A 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_credits | 402 | The call can't be covered by the balance, max_credits or the key's cap. See credits and billing. |
| account_suspended | 403 | The account is suspended. Reply to any WhichSitesUse email to sort it out. |
| not_found | 404 | No such endpoint. |
| rate_limited | 429 | Too many calls this minute. Includes retry_after_seconds and limit_per_minute, and REST also sends a Retry-After header. |
| internal | 500 | Something went wrong on our side. |
| billing_unavailable | 503 | Accounts can't be checked on the server right now. |
| snapshot_unavailable | 503 | The 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.
| Caller | Calls a minute | Counted per |
|---|---|---|
| No key (REST find_technologies and count_sites only) | 30 | IP address |
| Account that hasn't paid yet | 30 | Account |
| Account that has paid | 300 | Account |
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.