> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Error Reference

> Every error code the Searchable REST API returns, what it means, and how to fix it

## Overview

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

```json theme={null}
{
  "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`](#unauthorized) | 401 | Missing, malformed, revoked, or expired API key |
| [`sign_in_required`](#sign-in-required) | 401 | A public share page's "team only" workspace found no signed-in member session |
| [`forbidden`](#forbidden) | 403 | Access denied to the requested resource |
| [`missing_scope`](#missing-scope) | 403 | The API key lacks the required scope (`read`/`write`) or capability |
| [`plan_upgrade_required`](#plan-upgrade-required) | 403 | The workspace's plan doesn't include this feature |
| [`security_policy_denied`](#security-policy-denied) | 403 | The workspace's administrator has switched off API/MCP access, or report sharing |
| [`not_found`](#not-found) | 404 | The resource doesn't exist, or the key can't reach it |
| [`invalid_argument`](#invalid-argument) | 400 | A query parameter, path parameter, or body field is invalid |
| [`invalid_country`](#invalid-country) | 400 | An unrecognized `country` filter value |
| [`location_not_placed`](#location-not-placed) | 400 | A state or city that couldn't be placed — the default location was not changed |
| [`location_lookup_failed`](#location-lookup-failed) | 503 | The place lookup was unavailable — the default location was not changed |
| [`prompt_gates_failed`](#prompt-gates-failed) | 422 | A prompt candidate failed the import gates — nothing was created |
| [`no_domain`](#no-domain) | 400 | The project has no verified domain configured |
| [`no_workspace`](#no-workspace) | 400/403 | The project isn't linked to a workspace |
| [`no_pages`](#no-pages) | 400 | No tracked (or matching) pages to audit |
| [`bulk_limit_exceeded`](#bulk-limit-exceeded) | 400 | Too many pages requested for a bulk audit on this plan |
| [`quota_exceeded`](#quota-exceeded) | 403 | A monthly/concurrent usage quota is exhausted |
| [`project_not_runnable`](#project-not-runnable) | 403 | The project is paused or archived — background jobs are blocked |
| [`pitch_not_supported`](#pitch-not-supported) | 403 | The feature isn't available on pitch (scoped) projects |
| [`last_domain`](#last-domain) | 400 | Archiving would leave the workspace with no active project |
| [`stale_revision`](#stale-revision) | 409 | The prompt or project changed since the revision you sent |
| [`conflict`](#conflict) | 409 | A competitor or topic with that name or domain already exists |
| [`duplicate_domain`](#duplicate-domain) | 409 | A project or pitch already holds that domain |
| [`INACTIVE_PITCH_PROMPT_MUTATION`](#inactive-pitch-prompt-mutation) | 409 | A pitch project that isn't active is a frozen snapshot — no edits |
| [`pitch_allowance_used`](#pitch-allowance-used) | 403 | The workspace's pitch prompt allowance is spent |
| [`already_extended`](#already-extended) | 409 | The pitch's one extension is already used |
| [`extend_not_available_yet`](#extend-not-available-yet) | 409 | A pitch can be extended only in its last 48 hours |
| [`cannot_reactivate`](#cannot-reactivate) | 409 | The pitch has no days left and its extension is used |
| [`pitch_not_active`](#pitch-not-active) | 409 | The action needs an active pitch; this one is declined or expired |
| [`pitch_still_active`](#pitch-still-active) | 409 | The action applies only to a declined or expired pitch |
| [`no_refreshes_left`](#no-refreshes-left) | 409 | The pitch has used all its manual refreshes |
| [`refresh_failed`](#refresh-failed) | 503 | The refresh could not start; no refresh was used |
| [`already_converted`](#already-converted) | 409 | The pitch is a client project now |
| [`not_a_pitch`](#not-a-pitch) | 409 | The id is a regular project, not a pitch |
| [`preview_stale`](#preview-stale) | 409 | The move's preview is out of date, or the move was not confirmed against one |
| [`confirmation_mismatch`](#confirmation-mismatch) | 409 | The domain typed to confirm a move isn't the pitch's domain |
| [`destination_not_permitted`](#destination-not-permitted) | 409 | The pitch can't move into that workspace |
| [`cross_reseller_transfer_not_allowed`](#cross-reseller-transfer-not-allowed) | 409 | The move's destination belongs to another reseller |
| [`same_workspace`](#same-workspace) | 409 | The destination is the workspace the pitch is already in |
| [`destination_owner_missing`](#destination-owner-missing) | 409 | The destination workspace has no valid owner |
| [`project_state_unsupported`](#project-state-unsupported) | 409 | The pitch or the destination can't move in its current state |
| [`creator_domain_conflict`](#creator-domain-conflict) | 409 | The destination already holds a project of the pitch's creator on its domain |
| [`source_domain_conflict`](#source-domain-conflict) | 409 | The pitch's own workspace holds a live project of its creator on the same domain |
| [`access_removal_not_confirmed`](#access-removal-not-confirmed) | 409 | The move revokes access grants and `acknowledgedWarnings` doesn't confirm it |
| [`storage_object_missing`](#storage-object-missing) | 409 | One of the pitch's images has no storage object |
| [`quota_projects_exceeded`](#quota-projects-exceeded) | 409 | The destination is at its plan's project limit |
| [`quota_prompts_exceeded`](#quota-prompts-exceeded) | 409 | The pitch's prompts would exceed the destination's prompt allowance |
| [`in_flight_agent_runs`](#in-flight-agent-runs) | 409 | The agent is still working on the pitch |
| [`lock_timeout`](#lock-timeout) | 409 | The pitch is busy; the move was rolled back |
| [`serialization_failure`](#serialization-failure) | 409 | The pitch changed during the move; it was rolled back |
| [`not_active`](#not-active) | 409 | The reseller isn't active, so a new client can't be created |
| [`role_not_permitted`](#role-not-permitted) | 409 | A new client's staff role is above the roles you may assign |
| [`staff_not_in_tenant`](#staff-not-in-tenant) | 409 | A staff user on the new client doesn't belong to the reseller |
| [`staff_not_eligible`](#staff-not-eligible) | 409 | A staff user can't be added to the new client |
| [`invalid_scope`](#invalid-scope) | 400 | A source classification rule's scope isn't a subdomain or path of a domain |
| [`host_outside_domain`](#host-outside-domain) | 400 | A rule's scope isn't part of the domain sent as `withinDomain` |
| [`invalid_citation_type`](#invalid-citation-type) | 400 | A rule's `citationType` isn't a Source Type |
| [`missing_competitor`](#missing-competitor) | 400 | A `competitor` rule names no `competitorId` |
| [`unknown_competitor`](#unknown-competitor) | 400 | A rule's `competitorId` isn't one of the project's competitors |
| [`duplicate_scope`](#duplicate-scope) | 409 | The project already has a rule for that scope |
| [`rule_limit`](#rule-limit) | 409 | The project has reached its source classification rule limit |
| [`rate_limited`](#rate-limited) | 429 | Too many requests — usually the per-key REST limit, or an upstream Google limit |
| [`idempotency_in_flight`](#idempotency-in-flight) | 409 | A request with the same `Idempotency-Key` is still running |
| [`idempotency_conflict`](#idempotency-conflict) | 409 | An `Idempotency-Key` was reused with a different request body |
| [`audit_lock_busy`](#audit-lock-busy) | 409 | Another audit of the project is starting — retry after `Retry-After` |
| [`query_timeout`](#query-timeout) | 504 | The query took too long — narrow the request and retry |
| [`gsc_not_connected`](#gsc-not-connected) | 409 | No Google Search Console site linked to the project |
| [`gsc_site_not_linked`](#gsc-site-not-linked) | 404 | The linked GSC site record doesn't match the project |
| [`gsc_access_denied`](#gsc-access-denied) | 403 | Google revoked/denied access — reconnect the account |
| [`ga4_not_connected`](#ga4-not-connected) | 409 | No Google Analytics 4 property linked to the project |
| [`traffic_not_connected`](#traffic-not-connected) | 409 | No crawler-log, CDN, or tracker source connected |
| [`filters_invalid`](#filters-invalid) | 400 | The `filterSpec` payload is malformed or conflicts with legacy filter params |
| [`filters_unsupported`](#filters-unsupported) | 400 | A condition names a dimension, operator, or ref this endpoint doesn't support |
| [`filters_too_large`](#filters-too-large) | 400 | Too many values, too many conditions, or an oversized encoded payload |
| [`filters_not_enabled`](#filters-not-enabled) | 403 | The analytics filters surface isn't enabled for this user and project |
| [`filters_flag_unavailable`](#filters-flag-unavailable) | 503 | The filters feature flag couldn't be evaluated |
| [`filter_rules_bounds_exceeded`](#filter-rules-bounds-exceeded) | 400 | A request's metric rules exceed the project, rule-count, or resolved-id limits |
| [`filter_compile_invariant`](#filter-compile-invariant) | 500 | An internal invariant was violated while compiling filters |
| [`internal_error`](#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 **Manage Account → Integrations → API Keys**.

### `sign_in_required`

**401.** Returned by the public share endpoints — `GET /api/visibility/shared/{token}`, `GET /api/chat/shared/{token}`, and the `.../verify` routes on both — when the workspace that owns the shared report or conversation has its sharing policy set to "team only" and the request carries no signed-in session belonging to a member of that workspace.

**Fix:** Sign in as a member of the workspace that owns the report or conversation, then retry.

### `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, their role doesn't allow the change, such as a workspace viewer starting an audit, or the project is inactive).

**Fix:** Confirm the key's owning user is a member of the workspace that owns the resource, with a role that can make the change.

### `missing_scope`

**403.** The key doesn't carry the scope or capability the endpoint requires. Read endpoints, and generating a report, require `read`; starting an audit or refreshing a sitemap requires `write`; the endpoints that change a project's setup each need a [capability](https://docs.searchable.com/api-reference/introduction.md#capabilities). `admin` covers all of them.

**Fix:** A key's scopes can't be changed after it's created. Create a new key under **Manage Account → Integrations → API Keys**, with **Allow write access** on if it needs to make changes, which adds `write` and every capability. Then revoke the old key. See [Write access](https://docs.searchable.com/api-reference/introduction.md#write-access).

### `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, creating a pitch in a workspace whose plan has none, …). Often carries `requiresUpgrade: true`.

**Fix:** Upgrade the workspace's plan under **Settings → Billing**.

### `security_policy_denied`

**403.** The workspace that owns the requested project has API and MCP access switched off by a workspace-level security policy. This is an administered state, not a plan or scope problem: the key is valid, and it keeps working on any other workspace its owner belongs to — only requests that act on the restricted workspace's projects are refused. Never carries `requiresUpgrade`.

The same code is returned by the share-creating endpoints — including `POST /api/mcp/projects/{projectId}/reports` and the MCP server's `generate_report` tool (as a tool error result with `error.code`), both of which publish a shareable report — when the workspace's **report sharing** policy is switched off (*"Report sharing is turned off for this workspace."*). A "team only" sharing policy does not refuse creation; it only limits who can open the link.

**Fix:** Nothing on your side will clear it. The restriction is set by Searchable for the workspace at the customer's request; contact the workspace's administrator, or Searchable support, to have it lifted.

## 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](https://docs.searchable.com/advanced/api-usage.md#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.

### `prompt_gates_failed`

**422.** At least one candidate sent to `POST .../prompt-generation/import` failed the import gates (no em/en dash, no semicolon, the market's spelling, no near-duplicate), so the whole batch was refused and nothing was created. Carries `validation` (what each gate found) and `outcomes` (one row per candidate).

**Fix:** Rewrite or drop the refused candidates (`validation` says what each gate found), then import again.

### `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.

### `location_not_placed`

**400.** `PUT /projects/{projectId}/default-location` (and the MCP `set_default_location` tool) couldn't place the `state` or `city` you sent: it isn't a state or city the lookup knows in that country, or it's a US city found in more than one state. Nothing was changed. The message says which.

**Fix:** Check the spelling and the `country`, and send the city's `state` with a US city found in more than one state (for example `city: "Portland"`, `state: "Oregon"`).

### `location_lookup_failed`

**503.** The place lookup behind `PUT /projects/{projectId}/default-location` (and `set_default_location`) was unavailable, so the `state` or `city` couldn't be checked. Nothing was changed. Carries `retryable: true`.

**Fix:** Retry later. A `country` sent on its own needs no lookup.

### `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](mailto:support@searchable.com)**.

### `no_pages`

**400.** Every id in `pageIds` didn't match a page in this project, no page matches the `selection`, or the call named neither and the project has no pinned pages.

**Fix:** Pass valid `pageIds` for this project, or widen the `selection` (for `pinned`, pin at least one page first).

### `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`. Adding prompts checks the whole batch first: a batch that would go over the prompt allowance adds nothing.

**Fix:** Wait for the quota to reset (monthly quotas), reduce concurrent usage, or upgrade the plan. For prompts, archive some tracked prompts or add fewer.

### `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, sitemap sync, and archiving or reactivating a project are regular-project-only features.

**Fix:** This endpoint only supports regular (non-pitch) projects.

## Conflicts & project state

### `last_domain`

**400.** Archiving this project would leave its workspace with no active project, and a workspace keeps at least one.

**Fix:** Reactivate or create another project in the workspace first, then archive this one.

### `stale_revision`

**409.** The prompt or project changed since the revision you sent (`expectedRevision`, or `If-Match` when editing a prompt). Carries `currentRevision`.

**Fix:** Read the current state, check the change still makes sense, then retry with `currentRevision`.

### `conflict`

**409.** The item already exists: a competitor with that domain or name (when adding one with `source: "manual"`), or a topic with that name. A topic conflict carries the existing topic's id as `existingTopicId`.

**Fix:** Use the existing competitor or topic, or choose a different name.

### `duplicate_domain`

**409.** The workspace already has a project on that domain. `POST /api/mcp/pitches` refuses a domain you already have as a project or a pitch in any workspace you can reach, and names what holds it: `howToFix` says which project or pitch it is and what to do with it, and `existing` carries the whole holder: its `projectId`, `name`, `domain`, `workspaceId`, `workspaceName`, `isPitch`, `pitchStatus`, `isActive` and `canReactivate`. A holder in a workspace the API may not reach (API access switched off, or an IP allowlist you are outside) is named nowhere: the code and status are the same, but `existing` is absent and the message names no workspace.

Reactivating a pitch (`POST /api/mcp/pitches/{pitchId}/lifecycle` with `"action": "reactivate"`) answers `duplicate_domain` too, when another project or an active pitch in the pitch's workspace holds its domain. That holder is never named: there is no `existing`, and `howToFix` says to find it with `GET /api/mcp/pitches` or `GET /api/mcp/projects`.

**Fix:** Use the existing project or pitch, or create the new one on a different domain or in a different workspace. A closed pitch still holds its domain: reactivate it, or convert it to a client project. For a reactivation, reactivate once the project or pitch that holds the domain no longer does.

### `INACTIVE_PITCH_PROMPT_MUTATION`

**409.** The project is a pitch that is no longer active (declined, expired, archived or accepted), so it's a frozen review snapshot: its prompts, topics, competitors, brand profile and source classification rules can't be changed. The body is `{ error, code }`, not the problem format above.

**Fix:** Make the change on an active project instead.

## Pitches

These codes come from the pitch endpoints (`/pitches`). A pitch is a 7-day trial project for a prospect, with one 7-day extension and 5 manual refreshes; its prompts count against the workspace's pitch allowance, never the plan's prompt allowance. Creating a pitch can also answer [`plan_upgrade_required`](#plan-upgrade-required) (`requiresUpgrade: true`) when the workspace's plan has no pitches, and [`duplicate_domain`](#duplicate-domain).

### `pitch_allowance_used`

**403.** The workspace's pitch prompt allowance is fully used. Its active pitches share it, so a pitch can't be created or reactivated until prompts are freed.

**Fix:** Decline or convert an active pitch to free its prompts (`GET /api/mcp/pitches` shows each workspace's `allowance`), then retry.

### `already_extended`

**409.** A pitch has one 7-day extension and this pitch's is used.

**Fix:** Convert the pitch to a client project to keep it.

### `extend_not_available_yet`

**409.** A pitch can be extended only in its last 48 hours. Carries `opensAt`, the time extending opens.

**Fix:** Retry from `opensAt`. `GET /api/mcp/pitches` shows each pitch's `canExtend`.

### `cannot_reactivate`

**409.** A declined or expired pitch with no days left comes back only by using its one extension, and this pitch's is used.

**Fix:** Convert the pitch to a client project instead.

### `pitch_not_active`

**409.** The action works only on an active pitch, and this one is declined or expired.

**Fix:** Reactivate the pitch first, then retry.

### `pitch_still_active`

**409.** Reactivating, hiding and unhiding apply only to declined or expired pitches, and this pitch is active.

**Fix:** To hide an active pitch from the project picker, decline it first.

### `no_refreshes_left`

**409.** The pitch has used all its manual refreshes.

**Fix:** Convert the pitch to a client project to keep refreshing it.

### `refresh_failed`

**503.** The refresh could not start, and no refresh was used.

**Fix:** Retry in a minute.

### `already_converted`

**409.** The pitch was converted, so it is a regular client project now and no pitch action applies to it.

**Fix:** Use its id with the project endpoints; `GET /api/mcp/projects` lists it.

### `not_a_pitch`

**409.** The id belongs to a regular project, not a pitch.

**Fix:** Use the project endpoints with this id; they take it as it is.

## Moving a pitch into a client workspace

These codes come from a reseller's move of a pitch into a client workspace (`/api/mcp/pitches/{pitchId}/client-move`). Each is a 409, and nothing moves; a new client's refusals are rolled back whole, so no workspace is left behind. `preview_stale`, `confirmation_mismatch` and `destination_not_permitted` are the move's own checks; every other code here is the move engine's own, in lower case. `GET /api/mcp/pitches/{pitchId}/client-move` lists the `eligibleDestinations`, `assignableRoles` and `staffOptions` that several of the fixes below refer to.

### `preview_stale`

**409.** A reseller's move of a pitch into a client workspace (`POST /api/mcp/pitches/{pitchId}/client-move`) was not confirmed against a current preview: the pitch or the destination workspace changed since the preview was taken, no `previewSignature` was sent for an existing workspace, the signature never matched a preview, or `acknowledgedWarnings` isn't exactly the codes of the warnings the preview listed. Nothing moved.

**Fix:** Preview again with `POST /api/mcp/pitches/{pitchId}/client-move/preview`, have the user confirm what it lists, then send the move with the new `previewSignature`.

### `confirmation_mismatch`

**409.** `confirmDomain` isn't the pitch's domain. The user types the domain to confirm the move, as they do in the app. Nothing moved.

**Fix:** Ask the user to type the pitch's domain exactly as it is, then send the move again with what they typed.

### `destination_not_permitted`

**409.** The pitch can't move into that workspace: it is the pitch's own workspace, it belongs to another reseller, or you don't manage projects there.

**Fix:** `GET /api/mcp/pitches/{pitchId}/client-move` lists the workspaces the pitch can move into (`eligibleDestinations`); pick one of them.

### `cross_reseller_transfer_not_allowed`

**409.** The destination belongs to another reseller.

**Fix:** Pick a workspace from `eligibleDestinations`.

### `same_workspace`

**409.** The destination is the workspace the pitch is already in.

**Fix:** Pick another workspace from `eligibleDestinations`, or a new client.

### `destination_owner_missing`

**409.** The destination workspace has no valid owner.

**Fix:** Pick another destination, or give that workspace an owner first.

### `project_state_unsupported`

**409.** The pitch or the destination workspace was not found in a state that can move.

**Fix:** Check them with `GET /api/mcp/pitches/{pitchId}/client-move`, then preview again.

### `creator_domain_conflict`

**409.** The destination already holds a project of the pitch's creator on its domain.

**Fix:** Archive or move that project, or pick another destination.

### `source_domain_conflict`

**409.** The pitch's own workspace already holds a live project of its creator on the same domain, so the pitch can't be converted.

**Fix:** Archive that project, then retry.

### `access_removal_not_confirmed`

**409.** Moving the pitch revokes its access grants (API keys, invitations, integration tokens) and `acknowledgedWarnings` doesn't include `ACCESS_GRANTS_WILL_BE_REVOKED`.

**Fix:** Show the user the preview's warnings, and send the codes they confirm.

### `storage_object_missing`

**409.** One or more of the pitch's image records no longer has a matching storage object.

**Fix:** Contact support with the response's `requestId`.

### `quota_projects_exceeded`

**409.** The destination workspace is at its plan's project limit.

**Fix:** Upgrade that workspace or archive a project there, then preview again.

### `quota_prompts_exceeded`

**409.** The pitch's tracked prompts would put the destination over its plan's prompt allowance.

**Fix:** Upgrade that workspace or untrack prompts, then preview again.

### `in_flight_agent_runs`

**409.** The agent is still working on the pitch.

**Fix:** Retry once its runs have finished.

### `lock_timeout`

**409.** The pitch is busy right now; the move was rolled back.

**Fix:** Retry shortly.

### `serialization_failure`

**409.** The pitch changed while it was being moved; the move was rolled back.

**Fix:** Preview again, then retry.

### `not_active`

**409.** The reseller isn't active, so a new client workspace can't be created.

**Fix:** Move into an existing client workspace instead, or contact support.

### `role_not_permitted`

**409.** A `staff` role on the new client is above the roles you may assign.

**Fix:** Send only roles from `assignableRoles`.

### `staff_not_in_tenant`

**409.** A `staff` user on the new client doesn't belong to the reseller.

**Fix:** Send only users from `staffOptions`.

### `staff_not_eligible`

**409.** A `staff` user can't be added to the new client.

**Fix:** Send only users from `staffOptions`.

## Source classification rules

These codes come from the source classification rule endpoints (`/projects/{projectId}/sources/rules`), where a rule sets the Source Type of the citations under a subdomain or path of a cited domain. The same endpoints answer `403 forbidden` when your project role doesn't allow editing it (a Viewer's, for example). On a pitch project that is no longer active, every rule change and preview answers [`409 INACTIVE_PITCH_PROMPT_MUTATION`](#inactive-pitch-prompt-mutation).

### `invalid_scope`

**400.** The rule's `scope` isn't a subdomain or a path of a domain, so it can't name part of one.

**Fix:** Send a subdomain, a path or a URL, like `business.linkedin.com` or `linkedin.com/help`.

### `host_outside_domain`

**400.** The rule's `scope` isn't part of the domain you sent as `withinDomain`.

**Fix:** Send a scope under that domain, or leave `withinDomain` out.

### `invalid_citation_type`

**400.** The rule's `citationType` isn't one of the nine Source Types. A body naming an unknown type is usually refused earlier, with `invalid_argument`.

**Fix:** Send one of `brand`, `competitor`, `editorial`, `social`, `forum`, `review`, `institutional`, `third_party` or `other`.

### `missing_competitor`

**400.** A rule with `citationType: "competitor"` needs the competitor its citations belong to.

**Fix:** Send `competitorId`, the `id` of one of the project's competitors from `GET /projects/{projectId}/competitors`.

### `unknown_competitor`

**400.** The rule's `competitorId` isn't one of the project's competitors.

**Fix:** Take the id from `GET /projects/{projectId}/competitors`, or add the competitor first.

### `duplicate_scope`

**409.** The project already has a rule for that scope. Scopes are compared as the rule reads them, so `https://linkedin.com/help/` and `linkedin.com/help` are the same scope.

**Fix:** Change the existing rule with `PATCH /projects/{projectId}/sources/rules/{ruleId}` instead.

### `rule_limit`

**409.** The project has reached its limit of 200 source classification rules.

**Fix:** Remove rules you no longer need, or cover several paths with one broader rule.

## Rate limiting & timeouts

### `rate_limited`

**429.** Usually the per-API-key REST rate limit (600 requests/minute) was exceeded; on Google-backed endpoints (`/gsc/*`) it can also relay Google's own rate limit. `Retry-After` (seconds) is present when Searchable's limiter applied the limit and may be absent for an upstream limit; both carry `retryable: true`. See [Rate limiting](https://docs.searchable.com/advanced/api-usage.md#rate-limiting). Over MCP there is no 429: a tool returns `rate_limited` once a key or OAuth connection exceeds 600 tool calls per minute, with `retryable: true` and `retryAfterSeconds` in the error instead of a `Retry-After` header. The source-scout cooldown from `manage_associated_source` (where Associated Sources is enabled) also returns `rate_limited` over MCP, without `retryable`.

**Fix:** Over REST, back off for `Retry-After` seconds when present (otherwise about a minute), then retry. Over MCP, retry the tool-call limit after `retryAfterSeconds`, but never retry the source-scout cooldown automatically. 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](https://docs.searchable.com/advanced/api-usage.md#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.

### `idempotency_conflict`

**409.** The `Idempotency-Key` was already used for a request with a different body, so replaying the stored response would answer a different request. See [Idempotency](https://docs.searchable.com/advanced/api-usage.md#idempotency).

**Fix:** Use a new key for a different request; reuse a key only to retry the identical request.

### `audit_lock_busy`

**409.** `POST /audits` waited briefly for another audit of the same project (started in the app or through the API) to finish starting, and it was still starting. Nothing was started. Carries a `Retry-After` header (2 seconds) and `retryable: true`. The response is not stored against an `Idempotency-Key`.

**Fix:** Wait `Retry-After` seconds, then retry the same request (the same key is fine). Pages the other audit started come back counted in `skippedInFlightCount`.

### `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 linked to this project is visible to you.

**Fix:** Connect Google Analytics 4 under **Settings → Integrations**, or ask the teammate who linked it to share it with the project, 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**.

## Analytics filters

These codes come from the Searchable app's own session-authenticated routes. Analytics routes (the dashboard's data endpoints, and the report snapshots built from them) accept a `filterSpec` query parameter; every other session-authenticated app route refuses one with `filters_unsupported`. The REST API surfaces the rest of this page covers never return these codes.

### `filters_invalid`

**400.** The `filterSpec` query parameter is malformed — undecodable, an unrecognized version, an unknown dimension or operator, the same dimension named twice in one AND-group, a mix of a legacy per-dimension param with `filterSpec` for the same dimension (or with an OR-joined `filterSpec`), the `filterSpec` parameter repeated, or a join the endpoint doesn't allow.

**Fix:** Check the filter payload's encoding and make sure you're not sending both a legacy filter param and a `filterSpec` condition for the same dimension.

### `filters_unsupported`

**400.** The decoded filter set names a dimension, operator, or ref this endpoint doesn't support, or the endpoint doesn't support `filterSpec` at all.

**Fix:** Check the endpoint's documented supported dimensions and operators, and drop anything else from the request.

### `filters_too_large`

**400.** The filter set exceeds a bound — too many values in one condition, too many conditions, or the URL-encoded `filterSpec` payload exceeds the 10 KB size limit.

**Fix:** Reduce the number of values or conditions, or split the request.

### `filters_not_enabled`

**403.** Filters beyond the basic "is any of" aren't enabled for this user on this project. Requests using only "is any of" conditions are never refused this way.

**Fix:** This is a rollout gate, not a plan limit — contact **[support@searchable.com](mailto:support@searchable.com)** if you believe it should be enabled.

### `filters_flag_unavailable`

**503.** The feature flag controlling analytics filters couldn't be evaluated.

**Fix:** Retry the request. If it persists, contact **[support@searchable.com](mailto:support@searchable.com)**.

### `filter_rules_bounds_exceeded`

**400.** A request's metric rules (Your Prompts volume, difficulty, visibility score and similar) exceed a per-request bound: they span more than one project, there are too many metric rules in one request, or a rule resolves to more ids than the cap. Reserved — no endpoint returns it yet.

**Fix:** Apply metric rules to a single project, use fewer of them, or narrow each rule, then retry.

### `filter_compile_invariant`

**500.** An internal invariant was violated while compiling filters into a query (an unexpectedly empty value set, an unmapped dimension, or an unsupported operator reaching the compiler). Never caused by anything in your request.

**Fix:** Retry. If it persists, contact **[support@searchable.com](mailto:support@searchable.com)** with the `requestId`.

## 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](mailto: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](mailto:support@searchable.com)** with the endpoint, `requestId`, and response body.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.