API errors and rate limits

Errors return { "error": { "code": "…", "message": "…", "details": … } } with a matching HTTP status.

• 400 invalid_parameter: a query parameter such as since, until or outcome is malformed.
• 401 unauthorized: missing, invalid or revoked key.
• 403 plan_required: API access needs a Scale plan or above on at least one website.
• 403 insufficient_scope: the key is read-only.
• 429 cooldown, concurrency, daily_quota, monthly_quota, competitor_quota or host_busy: an SEO audit limit applies; see retry_at and Retry-After.
• 403 org_suspended: contact support.
• 404 not_found: the resource doesn't exist in your organisation.
• 409 conflict: the search term already exists for that country and device.
• 422 validation_failed / limit_exceeded / plan_required / project_unverified: see message and details.
• 429 rate_limited: wait for Retry-After seconds.
• 500 internal_error: try again; contact support if it persists.
• 503 unavailable: the API is temporarily unavailable; retry with backoff.

Rate limits

120 requests per minute per key. A 429 response includes Retry-After: 60. Every request is logged against the key, and the key's last-used time (updated at most once a minute) is shown in Settings → API keys.

Plan limits

Adding or changing terms never silently lowers your numbers: if a request would go over the website's search-term or clicks-per-day limit, it fails with 422 and tells you how much is left.