API Error Reference

Overview

Every error response from the REST API (/api/mcp/*, /api/v1/*, and the Looker Studio connector) is shaped as application/problem+json — a machine-readable envelope that additively extends the API’s original { error: "..." } shape. Existing integrations that only read error keep working unmodified.

{
  "type": "https://docs.searchable.com/api/errors#not_found",
  "title": "Not Found",
  "status": 404,
  "code": "not_found",
  "error": "Project not found or access denied",
  "message": "Project not found or access denied",
  "howToFix": "...",
  "requestId": "b3f1c2a0-4e9d-4a11-9c3a-8e2f6d1a7c55"
}

Field	Meaning
`type`	A URL identifying the error kind — always this page, anchored to `code`
`title`	Human-readable summary of `code`
`status`	The HTTP status code (matches the response status)
`code`	Machine-readable error code — stable, safe to branch on
`error`	Legacy compat key. Always equal to `message`. Existing integrations that read this keep working
`message`	Human-readable error message (identical to `error`)
`howToFix`	Present on actionable errors — a concrete next step
`requestId`	The request’s id. Include this when contacting support

Some errors carry additional fields beyond this base shape (e.g. requiresUpgrade, retryable, current/limit on a quota error) — those are documented per-code below and are additive, never replacing the fields above.

Quick reference

Code	Status	Meaning
`unauthorized`	401	Missing, malformed, revoked, or expired API key
`forbidden`	403	Access denied to the requested resource
`missing_scope`	403	The API key lacks the required `read`/`write` scope
`plan_upgrade_required`	403	The workspace’s plan doesn’t include this feature
`not_found`	404	The resource doesn’t exist, or the key can’t reach it
`invalid_argument`	400	A query parameter, path parameter, or body field is invalid
`invalid_country`	400	An unrecognized `country` filter value
`no_domain`	400	The project has no verified domain configured
`no_workspace`	400/403	The project isn’t linked to a workspace
`no_pages`	400	No tracked (or matching) pages to audit
`bulk_limit_exceeded`	400	Too many pages requested for a bulk audit on this plan
`quota_exceeded`	403	A monthly/concurrent usage quota is exhausted
`project_not_runnable`	403	The project is paused or archived — background jobs are blocked
`pitch_not_supported`	403	The feature isn’t available on pitch (scoped) projects
`rate_limited`	429	Too many requests — per-key REST rate limit, or a per-project concurrency cap
`idempotency_in_flight`	409	A request with the same `Idempotency-Key` is still running
`query_timeout`	504	The query took too long — narrow the request and retry
`gsc_not_connected`	409	No Google Search Console site linked to the project
`gsc_site_not_linked`	404	The linked GSC site record doesn’t match the project
`gsc_access_denied`	403	Google revoked/denied access — reconnect the account
`ga4_not_connected`	409	No Google Analytics 4 property linked to the project
`traffic_not_connected`	409	No crawler-log, CDN, or tracker source connected
`internal_error`	500	An unexpected server error — retry, then contact support

Authentication & authorization

`unauthorized`

401. The request has no Authorization: Bearer sea_... header, the key doesn’t start with sea_, or the key is invalid, revoked, or expired. Fix: Check the header is Authorization: Bearer sea_xxxxx. Create or rotate the key under Settings → Workspace → Integrations.

`forbidden`

403. The authenticated key’s user doesn’t have access to the requested resource (distinct from a missing scope or a not-found — the resource exists but this key’s user isn’t a member, or the project is inactive). Fix: Confirm the key’s owning user is a member of the workspace that owns the resource.

`missing_scope`

403. The key doesn’t carry the scope the endpoint requires. Read endpoints require read; write/action endpoints (report generation, triggering an audit, refreshing a sitemap) require write. admin covers both. Fix: Create a new key with the required scope, or use a key that already has it. See Scopes.

`plan_upgrade_required`

403. The action is gated behind a plan the workspace isn’t on (white-label branding, report sharing, Shopping Analytics, Looker Studio integration, query fanout, …). Often carries requiresUpgrade: true. Fix: Upgrade the workspace’s plan under Settings → Billing.

Not found & validation

`not_found`

404. The resource doesn’t exist, or the API key’s project binding doesn’t allow it to reach the requested project (a project-bound key can never see another project, even one its owning user can access in-app — see Scopes). Deliberately indistinguishable from “doesn’t exist” so existence never leaks to a caller who shouldn’t see it. Fix: Double-check the id in the URL. If the key is project-bound, confirm you’re calling it for its own project.

`invalid_argument`

400. A query parameter, path parameter, or request body failed validation (e.g. an out-of-range days, a malformed date, an invalid enum value, or a body that fails its schema). The response often carries details with the field-level breakdown. Fix: Check the parameter/body shape against the endpoint’s documented params.

`invalid_country`

400. The country filter value isn’t a recognized ISO code or name. Fix: Pass a valid ISO 3166-1 country code (e.g. US, GB) or locationId instead.

`no_domain`

400. The project has no verified domain — required before an audit or sitemap sync can run (the audited origin is always derived from the project’s own domain, never a caller-supplied URL). Fix: Set the project’s domain in the dashboard, then retry.

`no_workspace`

400 or 403. The project isn’t linked to a workspace, so plan/feature checks (Looker Studio, audits) have nothing to evaluate against. Fix: This is an account-configuration issue — contact support@searchable.com.

`no_pages`

400. POST /audits was called with no tracked pages and no explicit pageIds, or every id in pageIds didn’t match a page in this project. Fix: Track at least one page first, or pass valid pageIds for this project.

`bulk_limit_exceeded`

400. The requested page count for a single POST /audits call exceeds the workspace’s plan limit. Carries bulkLimitExceeded: true, requested, and maxAllowed. Fix: Pass a smaller pageIds list, split the audit into multiple calls, or upgrade the plan.

Quota & runnability

`quota_exceeded`

403. A monthly or concurrent usage quota (audits, reports, prompts, …) is exhausted. Carries quotaExceeded: true, current, and limit. Fix: Wait for the quota to reset (monthly quotas), reduce concurrent usage, or upgrade the plan.

`project_not_runnable`

403. The project is paused or archived. Background work (audits, sitemap sync, report generation) requires an active, non-archived project. Fix: Resume the project in the dashboard before retrying.

`pitch_not_supported`

403. The endpoint isn’t available for pitch (scoped, pre-conversion) projects — opportunities, audits, and sitemap sync are regular-project-only features. Fix: This endpoint only supports regular (non-pitch) projects.

Rate limiting & timeouts

`rate_limited`

429. Either the per-API-key REST rate limit (600 requests/minute) was exceeded, or — on some endpoints — a per-project concurrency cap was already held by another in-flight request from the same key. The response carries a Retry-After header (seconds) and retryable: true. See Rate limiting. Fix: Back off for Retry-After seconds, then retry. Spread bursts of requests across a longer window rather than firing them all at once.

`idempotency_in_flight`

409. Another request carrying the same Idempotency-Key is still executing — the duplicate was refused instead of running the side effect a second time. Carries a Retry-After header (5 seconds) and retryable: true. See Idempotency. Fix: Wait Retry-After seconds, then retry with the same key — once the original completes successfully you’ll receive its stored response (X-Idempotent-Replay: true); if the original failed, the retry runs fresh.

`query_timeout`

504. The query took longer than the endpoint’s timeout budget. Carries timeout: true and retryable: true. Fix: Narrow the days window or add filters (platform, topic, location), then retry.

Google integrations

`gsc_not_connected`

409. No Google Search Console site is linked to this project. Fix: Connect Google Search Console under Settings → Integrations, then retry.

`gsc_site_not_linked`

404. The project has a GSC site reference that doesn’t resolve — a narrower variant of “not connected” surfaced by some GSC endpoints. Fix: Reconnect Google Search Console under Settings → Integrations.

`gsc_access_denied`

403. Google denied the request — the connected account’s token was revoked, permission to the property was removed, or the property was unshared. Distinct from gsc_not_connected: the integration was connected, but Google is now rejecting it. Fix: Reconnect the Google account under Settings → Integrations.

`ga4_not_connected`

409. No Google Analytics 4 property is linked to this project. Fix: Connect Google Analytics 4 under Settings → Integrations, then retry.

AI Traffic

`traffic_not_connected`

409. No crawler-log, CDN, or Searchable-tracker data source is connected for this project. Fix: Connect a source under AI Traffic → Setup.

Server errors

`internal_error`

500. An unexpected server-side failure. Never leaks internal error text — the message is always a stable, generic description. Fix: Retry with exponential backoff. If it persists, contact support@searchable.com with the requestId from the response body.

Need more?

Higher rate limits, a code not listed here, or a question about a specific response? Contact support@searchable.com with the endpoint, requestId, and response body.

Getting Started

Using Searchable

Integrations

LLM Analytics Setup

Advanced Features

Changelog

Overview

Quick reference

Authentication & authorization

`unauthorized`

`forbidden`

`missing_scope`

`plan_upgrade_required`

Not found & validation

`not_found`

`invalid_argument`

`invalid_country`

`no_domain`

`no_workspace`

`no_pages`

`bulk_limit_exceeded`

Quota & runnability

`quota_exceeded`

`project_not_runnable`

`pitch_not_supported`

Rate limiting & timeouts

`rate_limited`

`idempotency_in_flight`

`query_timeout`

Google integrations

`gsc_not_connected`

`gsc_site_not_linked`

`gsc_access_denied`

`ga4_not_connected`

AI Traffic

`traffic_not_connected`

Server errors

`internal_error`

Need more?

​Overview

​Quick reference

​Authentication & authorization

​unauthorized

​forbidden

​missing_scope

​plan_upgrade_required

​Not found & validation

​not_found

​invalid_argument

​invalid_country

​no_domain

​no_workspace

​no_pages

​bulk_limit_exceeded

​Quota & runnability

​quota_exceeded

​project_not_runnable

​pitch_not_supported

​Rate limiting & timeouts

​rate_limited

​idempotency_in_flight

​query_timeout

​Google integrations

​gsc_not_connected

​gsc_site_not_linked

​gsc_access_denied

​ga4_not_connected

​AI Traffic

​traffic_not_connected

​Server errors

​internal_error

​Need more?

Overview

Quick reference

Authentication & authorization

`unauthorized`

`forbidden`

`missing_scope`

`plan_upgrade_required`

Not found & validation

`not_found`

`invalid_argument`

`invalid_country`

`no_domain`

`no_workspace`

`no_pages`

`bulk_limit_exceeded`

Quota & runnability

`quota_exceeded`

`project_not_runnable`

`pitch_not_supported`

Rate limiting & timeouts

`rate_limited`

`idempotency_in_flight`

`query_timeout`

Google integrations

`gsc_not_connected`

`gsc_site_not_linked`

`gsc_access_denied`

`ga4_not_connected`

AI Traffic

`traffic_not_connected`

Server errors

`internal_error`

Need more?