Skip to main content

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

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

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). 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.

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 (requiresUpgrade: true) when the workspace’s plan has no pitches, and 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.

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

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