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