Error codes

Every error follows RFC 9457 (application/problem+json). Your code relies on the code field, which is stable; the title is translated and may change.

• unauthenticated Missing, invalid or expired token.
• forbidden This token is not allowed to perform this action.
• token.missing_scope The token does not carry the required scope.
• api.not_in_plan The API is not included in your plan.
• api.write_not_in_plan Write access to the API is not included in your plan.
• plan_limit Your plan limit has been reached.
• rate_limited Your plan rate limit was exceeded, retry later.
• not_found Resource not found.
• method_not_allowed This route does not support this HTTP method.
• validation_failed The request contains invalid values.
• pagination.invalid_cursor Invalid pagination cursor, or one issued for another request.
• idempotency.key_required This write requires an Idempotency-Key header.
• idempotency.key_invalid Invalid Idempotency-Key header (1 to 255 visible ASCII characters).
• idempotency.key_reused This Idempotency-Key was already used for another request.
• idempotency.in_progress A request with this Idempotency-Key is still in progress.
• project.locked Read-only project: your plan no longer covers it. Nothing runs, everything stays readable.
• project.not_configured Incomplete project: declare its business model and create a campaign before launching a crawl.
• crawl.already_running A crawl is already running for this team; one crawl runs at a time.
• crawl.already_finished This crawl has already finished.
• crawl.target_refused The campaign target is not a public address.
• crawl.no_baseline No comparable crawl to compare with: a truncated crawl is never a baseline.
• recommendations.no_data No data source for this project: launch a crawl, or connect Search Console or your logs.
• export.crawl_not_finished This crawl has not finished: its report would be incomplete.
• export.not_ready The export is not ready yet.
• export.expired The export has expired; request a new one.
• positions.not_configured Position tracking is not configured: choose the tracked market first.
• keywords.project_limit Tracked keyword limit reached for this project.
• keywords.not_tracked This keyword is not tracked: track it first.
• keywords.paused This keyword is paused: resume it before checking it.
• keywords.already_checked_today This keyword was already checked today; one immediate check per keyword per day.
• bad_request Malformed request.
• conflict The request conflicts with the current state of the resource.
• payload_too_large Request body too large.
• unsupported_media_type Unsupported content type.
• service_unavailable Service temporarily unavailable.
• internal_error Internal error. It has been logged.

Plan refusals form a family: plan_limit followed by the plan key concerned, for instance plan_limit.projects.max. The response also carries entitlement and upgrade_to.

API reference Webhook events API documentation

This page in Markdown