The error body shape, every error code the RankParse API returns, whether you are charged, and how to retry safely.

Failed requests return a non-2xx HTTP status and a JSON body with a stable machine-readable code. Branch on code, not on the human-readable text, which can change.

Error body

402 Payment Required

{
  "error": "Payment Required",
  "code": "insufficient_credits",
  "message": "Add credits at https://rankparse.com/pricing"
}

Field	Meaning
`code`	Stable identifier. Always present on errors the API raises deliberately.
`error`	Short label, normally the HTTP status text (`Bad Request`, `Too Many Requests`).
`message`	Human-readable explanation, often with the fix.
`retry_after`	Seconds to wait. Present on daily quota errors and on retryable `503` errors.
`retry`	`true` or `false` on data store `503` errors, telling you whether an identical retry can succeed.

Variations you should handle:

Live fetch endpoints (page-seo, tech-stack, site-health, schema-markup, sitemap) return error as a short description such as Invalid URL and may omit message.
Approval inbox, agent task and some outreach errors set error to the same value as code.
Unexpected server faults return { "error": "Internal Server Error", "message": "..." } with no code.
Unknown routes return a plain text 404 Not Found, not JSON.

A domain with no data is never an error. It returns 200 with data: []. See Response format.

Order of checks

Requests are checked in this order, and the first failure wins. This tells you whether you were charged.

Authentication (401)
Role permission (403 capability_missing)
Per-key rate limit (429 rate_limited)
Input validation, on every data lookup and live page endpoint, batch and platform-domains.
Credit check and charge (402)
The work itself. If the work throws (a data store timeout, an upstream outage) or ends in an error response, the charge is refunded.

Are you charged?

Failure	Charged?
`401`, `403`, `429`	No. These happen before billing.
`402`	No. The charge itself was refused.
Validation `400` (a missing or invalid `domain`, `domains`, `url` and so on)	No. Checked before any charge on every data lookup and live page endpoint, and on `batch` and `platform-domains`. `indexnow` refunds instead.
`503 query_timeout`, `upstream_error`, `deterministic_timeout`	No. The charge is refunded automatically.
A `similar-domains` or `competitor-gap` answer that is partial and has no rows	No. Not charged: `credits_used` is `0`. A partial answer with rows is charged.
Live fetch failures (`fetch_failed`, `timeout`, `private_ip`, `response_too_large`)	No. Refunded.
`429` and `503` on `page-performance` (`quota_exceeded`, `user_quota_exceeded`, `psi_unavailable`)	No. `page-performance` charges only after Google returns a result.
`IndexNow` errors (any non-2xx from `POST /v1/indexnow`)	No. Refunded.
`503 wayback_unavailable` on `crawl-history`	No. Refunded.
Free routes (rank tracking, Search Console, Google Ads, issues, indexing, AI visibility scan, site audit, project context, approval inbox, outreach, Zeekeo)	Never charged.
Partial results	Yes, at the normal price, except `domain-authority` when the score is unavailable.

Error codes

Authentication and permissions

Status	Code	Meaning	What to do
`401`	`invalid_api_key`	The `X-API-Key` header is missing, the key is unknown or revoked, or its workspace was deleted.	Send a valid key. See Authentication.
`401`	`internal_auth_invalid`	A credential reserved for RankParse's own services was rejected.	Not for public use. Use an API key.
`403`	`capability_missing`	Your role in the workspace does not allow this action (for example a member trying to buy credits or manage billing).	Ask a workspace owner or admin, or use a key from a role that has access.
`404`	`key_not_found`	`DELETE /v1/keys/:id` named a key that does not exist, is already revoked, or belongs to someone else.	List keys with `GET /v1/keys` and retry with a current id.
`404`	`user_not_found`	The authenticated user record could not be found.	Contact support.

Credits and billing

Status	Code	Meaning	What to do
`402`	`insufficient_credits`	The balance is lower than the call costs.	Buy credits or enable auto recharge. See Credits. Retrying does not help until the balance rises.
`402`	`spend_cap_reached`	The workspace hit its monthly spend cap.	Raise the cap in Settings, Credits or wait for the next calendar month (UTC).
`400`	`invalid_credits`	`POST /v1/checkout` was given fewer than 100 credits or a non-integer.	Send an integer of at least 100.
`500`	`checkout_failed`	Stripe checkout could not be created.	Retry.
`402`	`plan_limit_reached`	The workspace plan does not cover this, for example launching an outreach campaign whose website or mailbox is beyond the plan's limit. Nothing was queued.	Upgrade the plan, or archive another website or mailbox.

Plans and subscriptions

POST /v1/subscription/checkout and POST /v1/subscription/portal are for the workspace owner (they need the billing.manage permission).

Status	Code	Meaning	What to do
`400`	`invalid_plan`	`plan` is not `pro` or `agency`, or `interval` is not `month` or `year`.	Fix the body.
`400`	`invalid_return_to`	`return_to` was given and is not `onboarding`.	Remove it or send `onboarding`.
`400`	`no_stripe_customer`	The billing portal was asked for a workspace with no billing history.	Subscribe or buy credits first.
`404`	`subscriptions_not_enabled`	Subscriptions are not available through the API yet.	Use Settings, Plan in the dashboard.
`409`	`already_subscribed`	The workspace already has a live plan.	Change or cancel it from the billing portal.
`500`	`portal_failed`	The Stripe billing portal could not be opened.	Retry.

Validation (all endpoints)

Status	Code	Meaning	What to do
`400`	`invalid_domain`	`domain` is missing or is not a bare hostname (letters, digits, dots and hyphens, at least one dot, up to 253 characters). `https://stripe.com` is rejected.	Send a hostname such as `stripe.com`.
`400`	`invalid_domains`	`domains`, `domain_a`, `domain_b` or `vs` is missing or has too few valid domains (`domain-overlap` needs at least 2). On `batch`, `domains` must be a non-empty array with at least one valid entry.	Fix the parameter.
`400`	`too_many_domains`	More domains than allowed (`domain-overlap` allows 5, `batch` allows 50).	Split the request.
`400`	`same_domain`	`competitor-gap` was called with `domain` equal to `vs`.	Compare two different domains.
`400`	`invalid_sort`	`sort` on `backlinks` is not `importance` or `recent`.	Use a supported value.
`400`	`invalid_from_domain`	`from_domain` on `backlinks` is not a valid domain.	Fix the value.
`400`	`invalid_link_type`	`link_type` on `backlinks` has invalid characters.	Use letters, digits, `_` or `-`, up to 32 characters.
`400`	`invalid_url`	`url` is missing or is not a valid public `http` or `https` URL (no credentials, no `#` fragment, no surrounding whitespace). Also returned when `domain` is invalid on the live endpoints `tech-stack`, `site-health` and `sitemap`.	Send a full public URL, or a bare hostname for domain endpoints.
`400`	`private_ip`	The URL or domain points at a private or reserved address.	Use a publicly reachable host.
`400`	`missing_platform`	`platform-domains` was called without `platform`.	Add `platform`.
`400`	`unknown_platform`	`platform` is not one of the supported platforms. The message lists them.	Use a listed platform.
`400`	`filter_not_available`	`registered_after`, `registered_before` or `country` was sent to `platform-domains`.	Remove the filter.

Rate and quota limits

Status	Code	Meaning	What to do
`429`	`rate_limited`	More than 60 requests in the last minute for this key.	Back off and retry. See Rate limiting.
`429`	`quota_exceeded`	On `page-performance`: the shared daily PageSpeed quota is used up. `retry_after` is the seconds until 00:00 UTC. On `/v1/tools/*`: the free daily limit for your IP or account is used up, with `reset_at` as a millisecond timestamp.	Wait for the reset.
`429`	`user_quota_exceeded`	You made 50 `page-performance` calls today (UTC), cached calls included.	Try again after 00:00 UTC.
`429`	`tools_quota_exceeded`	The free `page-speed` tool's daily capacity is used up.	Try again tomorrow.
`429`	`google_ads_user_quota_exceeded`	You used your 100 Google Ads keyword calls today (UTC).	Wait until 00:00 UTC (`retry_after`).
`429`	`google_ads_daily_quota_exceeded`	The service-wide Google Ads allowance is used up for today.	Wait until 00:00 UTC (`retry_after`).

Data store and live fetch

Status	Code	Meaning	What to do
`503`	`query_timeout`	The data query timed out. Usually transient. Includes `retry: true`, `retry_after: 3` and a `Retry-After: 3` header.	Retry the same request. For very large domains, lower `limit`.
`503`	`upstream_error`	The data store was briefly unavailable. Same retry fields as above.	Retry the same request after a few seconds.
`503`	`deterministic_timeout`	This exact input is too expensive to finish in budget (seen on `competitor-gap`). `retry: false`.	Do not retry unchanged. Narrow the request or lower `limit`.
`503`	`fetch_failed`	The target site could not be fetched (DNS failure, connection error, too many redirects, blocked).	Check the site is public and online, then retry later.
`503`	`timeout`	The target site did not respond in time.	Retry later.
`400`	`fetch_failed`, `timeout`	On `site-health`, fetch problems are reported as `400` instead of `503`. Refunded.	Same advice.
`400`	`response_too_large`	The target page exceeded the size the API reads. Refunded.	Choose a lighter page.
`503`	`psi_unavailable`	Google PageSpeed Insights failed or is unavailable.	Retry later. You were not charged.
`503`	`wayback_unavailable`	On `crawl-history`, none of the Wayback Machine lookups answered.	Retry later. You were not charged.
`500`	`tool_failed`	A free tool failed in an unclassified way.	Retry.

Free tools

The /v1/tools/* routes are built for the RankParse website and require a captcha token plus a per-IP or per-account daily allowance. See Free tools.

Status	Code	Meaning	What to do
`400`	`invalid_input`	The domain or URL input is missing or invalid.	Fix the input.
`403`	`turnstile_failed`	The captcha challenge failed.	Refresh and try again.
`429`	`quota_exceeded`	Free daily limit reached. The body has `reset_at`.	Sign up or wait for the reset.

Rank tracking

Status	Code	Meaning	What to do
`404`	`rank_tracking_site_not_found`	No rank tracking site with that `site_id` belongs to this workspace.	List sites with `GET /v1/rank-tracking/sites`.
`404`	`rank_tracking_keyword_not_found`	No tracked keyword with that `keyword_id` on this site.	List keywords first.
`400`	`invalid_rank_tracking_engine`	`engine` is not valid (`all`, `google`, `bing`, `yandex`; history accepts only a single engine).	Use a supported value.
`400`	`rank_tracking_provider_disabled`	The engine is valid but not enabled for this account.	Pick an enabled engine (see `enabled_engines` on the rankings response).
`400`	`invalid_rank_tracking_period`	`period_days` is not an integer in the allowed range (1 to 90).	Fix the value.
`400`	`invalid_rank_tracking_date`	`start_date` or `end_date` is missing, not `YYYY-MM-DD`, out of order, or spans more than 400 days.	Fix the dates.
`400`	`invalid_rank_tracking_dimension`	`dimension` is not `total` or `device`.	Fix the value.
`400`	`invalid_rank_tracking_alert_settings`	A `PATCH` to alert settings had an invalid field (`move_threshold` outside 1 to 50, `min_clicks` not a whole number from 0 to 100000, bad `email_override`, wrong types).	Fix the field named in `message`.
`400`	`rank_tracking_property_not_attached`	History was requested for an engine with no primary property attached to the site.	Attach a property in the dashboard.

Issues, indexing and AI visibility

Status	Code	Meaning	What to do
`400`	`invalid_issue_type`	`type` on `/v1/issues` is not a comma-separated list of `not-indexed`, `click-drop`, `low-ctr`, `connection`, `ai-visibility`, `site-health`, `provider-problem`.	Fix the value.
`400`	`invalid_indexing_status`	`status` on `/v1/indexing` is not `all`, `not_indexed`, `unchecked`, `indexed` or `error`.	Fix the value.
`404`	`issues_site_not_found`, `indexing_site_not_found`, `site_scan_site_not_found`	No website with that `site_id` in this workspace.	Call `GET /v1/websites`.
`400`	`site_scan_not_verified`	A re-check was asked for a website that is not verified through Search Console or Bing Webmaster Tools.	Verify the website first. `GET /v1/site-scan` answers `200` with `eligible: false` instead.
`403`	`site_scan_plan_required`	A re-check was asked on the Free plan.	Upgrade to a paid plan. `GET /v1/site-scan` answers `200` with `eligible: false` instead.
`400`	`site_scan_invalid_host`	The website has no host that can be scanned.	Check the website's address in the dashboard.

A re-check inside the 10 minute window is not an error: it answers 200 with status: "throttled" and retry_after_seconds. See Issues, Indexing and AI visibility scan.

Site audit and project context

Status	Code	Meaning	What to do
`404`	`site_audit_site_not_found`, `site_context_site_not_found`	No website with that `site_id` in this workspace.	Call `GET /v1/websites`.
`404`	`site_audit_not_found`	`audit_id` is not an audit of this website.	Take an id from `history` in `GET /v1/site-audit`.
`400`	`site_audit_not_verified`	An audit was asked for a website that is not verified through Search Console or Bing Webmaster Tools.	Verify the website first. The read operations answer `200` with `eligible: false` instead.
`403`	`site_audit_plan_required`	An audit was asked on the Free plan.	Upgrade to a paid plan. The read operations answer `200` with `eligible: false` instead.
`400`	`site_audit_invalid_host`	The website has no host that can be crawled.	Check the website's address in the dashboard.
`400`	`site_audit_invalid_request`	`max_pages` is not an integer of at least 10, the body is not JSON, or `issue_id`, `severity`, `status`, `indexable`, `limit` or `offset` is not valid.	Fix the value named in `message`.
`400`	`invalid_site_context`	The body of a project context update is invalid (unknown field, value too long, a competitor that is not a domain, a key page that is not an `http(s)` URL, nothing to change), or `log_limit` is not 0 to 100.	Fix the field named in `message`.
`400`	`site_context_limit_reached`	The update would leave more than 20 competitors or 30 key pages.	Remove entries first.
`409`	`site_context_conflict`	Another write changed the project context while this one was saving.	Repeat the request.

Starting an audit while one is running, or within 30 minutes of the last, is not an error: it answers 200 with status: "already_running" or "throttled". See Site audit and Project context.

Google Search Console

Status	Code	Meaning	What to do
`400`	`gsc_not_connected`	No Google Search Console connection on this workspace.	Connect it under Settings, Connections.
`401`	`gsc_token_expired`	The Google connection expired or was revoked.	Reconnect in the dashboard.
`403`	`gsc_access_denied`	No access to that property, and no property of yours matches the value.	Use one of the `valid_properties` in the response.
`404`	`gsc_property_not_found`	The property is not visible to any connected Google account.	Check the `site` value and connected accounts.
`429`	`gsc_quota_exceeded`	Google's Search Console API quota was exceeded.	Retry later.
`502`	`gsc_token_refresh_failed`	Google would not refresh the access token.	Retry shortly.
`502`	`gsc_api_error`	Google returned an unexpected error.	Retry.
`503`	`token_refresh_in_progress`	Another request was refreshing the Google token and did not finish in time.	Wait the `Retry-After` seconds and retry the same request.
`503`	`gsc_not_configured`	The integration is not configured on the server.	Contact support.
`400`	`bing_not_connected`, `yandex_not_connected`	Bing Webmaster Tools or Yandex Webmaster is not connected on this workspace.	Connect it under Settings, Connections, signing in with the account that has the website verified.
`401`	`bing_token_expired`, `yandex_token_expired`	The connection needs to be reconnected, or the provider rejected it.	Reconnect it under Settings, Connections.
`404`	`bing_site_not_found`, `yandex_site_not_found`	No verified website matches `site`.	Use one of the `valid_properties` in the response, or add and verify the website with the provider.
`400`	`bing_data_not_ready`	Bing has not made this data available yet, usually after a recent verification.	Try again in a few days.
`400`	`bing_request_rejected`	Bing rejected the request: the page may be unknown to it, or the method may not be available for the account.	Try another page or website. Retrying the same request fails again.
`400`	`yandex_data_not_ready`	Yandex has not loaded or indexed this host yet.	Try again later.
`404`	`yandex_query_not_found`	A query trend was asked for a query that is not among the host's popular queries for those dates.	Use a wider date range, or check the spelling.
`429`	`bing_daily_cap_reached`, `yandex_daily_cap_reached`	The workspace used its 300 live reads for the last 24 hours.	Do not retry now. Read the stored data with Get rankings.
`400`	`missing_site`, `missing_params`, `missing_dates`, `invalid_date`, `invalid_dimensions`, `invalid_search_type`, `invalid_param`, `conflicting_filters`, `invalid_filter_regex`	A query parameter is missing or invalid. The `message` names it. `filterPage` and `filterPageContains` cannot be combined, nor `filterQuery` and `filterQueryContains`, nor `filterQueryRegex` and `minQueryWords`.	Fix the parameter.

Google Ads keyword research

Status	Code	Meaning	What to do
`400`	`google_ads_not_connected`	Google Ads is not connected.	Connect it under Settings, Connections.
`400`	`google_ads_no_account_selected`	Connected, but no Ads account chosen.	Select an account in the dashboard.
`400`	`google_ads_invalid_request`	Google rejected the request (often a bad language or location resource name).	Use names like `languageConstants/1000` and `geoTargetConstants/2840`.
`400`	`invalid_language`	`language` is not a language resource name.	Use `languageConstants/<id>`.
`400`	`invalid_geo_target`	`geo_target_constants` is not an array of location resource names.	Use `geoTargetConstants/<id>`.
`400`	`invalid_json`	The body is not valid JSON.	Send valid JSON.
`400`	`missing_seed`	`keyword-ideas` needs `keywords` and/or `url`.	Provide a seed.
`400`	`missing_keywords`	`keyword-metrics` needs a `keywords` array.	Provide keywords.
`401`	`google_ads_token_expired`	The Google Ads connection expired.	Reconnect in the dashboard.
`403`	`google_ads_developer_token_not_approved`	RankParse's Google Ads access level is still pending, so live data is unavailable. Nothing is wrong with your account.	Try again later.
`403`	`google_ads_customer_not_enabled`	The selected Ads account is inactive (never set up or deactivated).	Pick another account or activate this one.
`403`	`google_ads_access_denied`	Google denied the request, for example a manager (MCC) account was selected. Manager accounts are not supported.	Select a regular Ads account.
`404`	`google_ads_account_not_found`	The selected account was not found.	Reselect the account.
`429`	`google_ads_quota_exceeded`	Google's own API quota was exceeded.	Retry later.
`502`	`google_ads_token_refresh_failed`	The access token could not be refreshed.	Retry shortly.
`502`	`google_ads_api_error`	Google Ads returned an unexpected error.	Retry.
`503`	`google_ads_not_configured`	The integration is not configured on the server.	Contact support.

The Google Ads daily limits (google_ads_user_quota_exceeded, google_ads_daily_quota_exceeded) are listed under rate and quota limits above. A call counts against them only after Google returns a successful answer.

IndexNow

Status	Code	Meaning	What to do
`400`	`indexnow_invalid_url`	`urls` is missing, empty, not an array of strings, contains a non-public or non-`http(s)` URL, or uses an explicit port.	Send full public URLs on the default port.
`400`	`indexnow_too_many_urls`	More than 1000 URLs.	Split into batches of 1000.
`400`	`indexnow_host_mismatch`	The URLs span more than one host.	Submit one host per call.
`400`	`indexnow_host_not_a_website`	The URLs' host is not a website in your workspace.	Add the site in the dashboard first.
`400`	`indexnow_key_not_found`	No key exists for the host.	Create one with `POST /v1/indexnow/key?domain=`.
`400`	`indexnow_key_not_verified`	The key file is not hosted at its key location (30 second check).	Host a text file containing exactly the key, then retry.
`400`	`indexnow_invalid_request`	IndexNow rejected the submission as malformed.	Check the URL list.
`403`	`indexnow_key_rejected`	IndexNow no longer accepts the key. The cached verification is cleared.	Confirm the key file is still hosted, then retry.
`422`	`indexnow_url_mismatch`	The URLs do not belong to the submitted host or the key does not match.	Check the host and key.
`429`	`indexnow_rate_limited`	IndexNow rate limit reached.	Slow down and retry later.
`503`	`indexnow_unavailable`	IndexNow is unreachable or returned an unexpected status.	Retry later.

Approval inbox and agent tasks

These routes (/v1/proposals, /v1/websites, /v1/activity, /v1/agent-tasks, /v1/client-report) set error equal to code. See Approval inbox.

Status	Code	Meaning	What to do
`400`	`invalid_proposal_input`	The body, `kind`, `site_id`, `client_request_id` or `status` filter is invalid. The `message` says which.	Fix the input.
`400`	`kind_not_available`	That proposal kind is not available.	Use `indexnow_submit` or `outreach_send`.
`400`	`invalid_activity_input`	The activity note is malformed.	Provide `summary` and optional fields as documented.
`400`	`invalid_client_report_input`	`site_id` is missing or `week_start` is not a Monday date that is not in the future.	Fix the input.
`400`	`invalid_task_summary`	Task `summary` is missing or too long.	Fix the summary.
`400`	`site_host_mismatch`	The URLs do not belong to the website named.	Use URLs on that website.
`400`	`gmail_not_connected`	A proposed or launched outreach send needs Gmail connected, or the connection needs to be reconnected because Google stopped accepting it.	Connect or reconnect Gmail under Settings, Connections.
`400`	`campaign_site_mismatch`, `sending_provider_unsupported`, `no_contacts`	The campaign cannot be proposed as sent.	See Outreach.
`400`	`nothing_approved`	An approved outreach proposal ran with no approved emails on the campaign.	Approve emails on the campaign first.
`403`	`approval_inbox_not_enabled`	The inbox is not enabled for this account yet.	Contact support.
`403`	`action_disabled_by_policy`	The user turned this action off in website settings.	Ask the user.
`403`	`invalid_request_source`	The proposal source is not allowed for this caller.	Use the documented request.
`404`	`site_not_found`	No website with that id in this workspace.	Call `GET /v1/websites`.
`404`	`proposal_not_found`	No proposal with that id.	List proposals.
`404`	`task_not_found`	No agent task with that id.	List tasks.
`404`	`campaign_not_found`	No campaign with that id in this workspace.	List campaigns.
`404`	`tracked_query_not_found`	No tracked query with that id on the website.	Check the id.
`409`	`task_not_claimable`	The task is done, expired or claimed by another agent.	Pick another task.
`409`	`change_in_progress`	A different change was already approved and is running.	Wait, then send again.
`429`	`too_many_pending_proposals`	A website already has 25 proposals waiting.	Ask the user to review the inbox.
`429`	`daily_proposal_limit_reached`	100 new proposals were created today.	Try again tomorrow.
`429`	`activity_limit_reached`	200 activity notes were logged today.	Try again tomorrow.

Outreach

Status	Code	Meaning	What to do
`400`	`invalid_json`	The body is not valid JSON.	Send valid JSON.
`400`	`invalid_name`	Campaign `name` is missing or longer than 200 characters.	Fix the name.
`400`	`invalid_domain`	`your_domain` is missing.	Add it.
`400`	`invalid_site_id`	`site_id` is not a non-empty string.	Fix or omit it.
`400`	`no_contacts`, `too_many_contacts`	The contacts array is empty or over the per-call limit.	Send a valid batch.
`400`	`invalid_updates`, `too_many_updates`	`contacts` on `/contacts/update` is empty, malformed or over 100 entries.	Send up to 100 `{email, subject, body}` objects.
`400`	`invalid_send_cap`, `invalid_auto_send`, `nothing_to_update`	Sending settings were invalid or empty. `max_sends_per_day` must be 1 to 100.	Fix the body.
`400`	`invalid_mailbox_id`	`mailbox_id` in a `PATCH /v1/outreach/sending` body is not a string.	Use a `mailbox_id` from `GET /v1/outreach/sending`.
`400`	`gmail_not_connected`, `sending_provider_unsupported`	Gmail is required for sending from the API.	Connect Gmail.
`402`	`plan_limit_reached`	The campaign's website or mailbox is beyond the plan's limit, so nothing was queued.	Upgrade, or archive another website or mailbox.
`403`	`human_only_setting`	The request tried to turn on sending without review. Only a person can, in the dashboard.	Ask the user.
`404`	`campaign_not_found`, `site_not_found`, `mailbox_not_found`	The campaign, website or mailbox does not belong to this workspace.	List yours.
`409`	`campaign_not_editable`, `campaign_launch_in_progress`, `change_in_progress`	The campaign or sending state does not allow this now.	Retry shortly.

See Outreach.

LinkedIn automation (Zeekeo)

The /v1/zeekeo/* routes act through the workspace's own connected Zeekeo account.

Status	Code	Meaning	What to do
`400`	`zeekeo_not_connected`	No Zeekeo account is connected.	Connect it under Settings, Connections.
`400`	`invalid_json`, `missing_campaign_id`, `missing_linkedin_url`, `missing_body`, `missing_subject`, `missing_name`, `missing_invite_template_id`, `missing_target`, `invalid_target`, `invalid_type`, `invalid_invite_limit`, `invalid_invite_delay`, `invalid_followup_delay_hours`	A body field is missing or invalid. The `message` names it.	Fix the body.
`401`	`zeekeo_auth_failed`	Zeekeo rejected the connected key (revoked or rotated).	Reconnect Zeekeo.
`429`	`zeekeo_rate_limited`	Zeekeo's own rate limit.	Wait a few seconds and retry.
`502`	`zeekeo_send_failed`, `zeekeo_activate_failed`	Zeekeo did not confirm the message was sent or the campaign started.	Check Zeekeo before retrying, to avoid a duplicate message.
`502`	`zeekeo_api_error`	Zeekeo returned an unexpected error.	Retry.
`503`	`zeekeo_not_configured`	The integration is not configured on the server.	Contact support.

Handling errors

Which errors to retry

Class	Examples	Retry?
Transient server errors	`query_timeout`, `upstream_error`, `500`, `502`, `503 psi_unavailable`, `wayback_unavailable`, `indexnow_unavailable`	Yes. Exponential backoff with jitter, a handful of attempts.
Rate limit	`rate_limited`	Yes, after a pause. Sliding window of 60 seconds.
Daily quotas	`quota_exceeded`, `user_quota_exceeded`, `google_ads_*_quota_exceeded`	Not until the reset time in `retry_after` (00:00 UTC).
Target site problems	`fetch_failed`, `timeout`	Maybe once or twice. The site may be down.
Credits	`insufficient_credits`, `spend_cap_reached`	No. Fix the balance or the cap first.
Client errors	Other `400`, `402 plan_limit_reached`, `403`, `404`, `409`, `422`	No. Change the request.
Auth	`invalid_api_key`	No. Fix the key.
Non-retryable data errors	`deterministic_timeout` (`retry: false`)	No. Narrow the request.

Retrying a request that failed with a refunded error is safe: you were not charged for the failed attempt.

Code samples

curl -i "https://api.rankparse.com/v1/domain-authority?domain=github.com" \
  -H "X-API-Key: rp_your_key"
# Inspect the status line, then the JSON body's "code" field.

Errors

Error body

Order of checks

Are you charged?

Error codes

Authentication and permissions

Credits and billing

Plans and subscriptions

Validation (all endpoints)

Rate and quota limits

Data store and live fetch

Free tools

Rank tracking

Issues, indexing and AI visibility

Site audit and project context

Google Search Console

Google Ads keyword research

IndexNow

Approval inbox and agent tasks

Outreach

LinkedIn automation (Zeekeo)

Handling errors

Which errors to retry

Code samples

Rate limiting

Credits

Response format

On this page

Errors

Error bodyCopy Anchor Link

Order of checksCopy Anchor Link

Are you charged?Copy Anchor Link

Error codesCopy Anchor Link

Authentication and permissionsCopy Anchor Link

Credits and billingCopy Anchor Link

Plans and subscriptionsCopy Anchor Link

Validation (all endpoints)Copy Anchor Link

Rate and quota limitsCopy Anchor Link

Data store and live fetchCopy Anchor Link

Free toolsCopy Anchor Link

Rank trackingCopy Anchor Link

Issues, indexing and AI visibilityCopy Anchor Link

Site audit and project contextCopy Anchor Link

Google Search ConsoleCopy Anchor Link

Google Ads keyword researchCopy Anchor Link

IndexNowCopy Anchor Link

Approval inbox and agent tasksCopy Anchor Link

OutreachCopy Anchor Link

LinkedIn automation (Zeekeo)Copy Anchor Link

Handling errorsCopy Anchor Link

Which errors to retryCopy Anchor Link

Code samplesCopy Anchor Link

RelatedCopy Anchor Link

Rate limiting

Credits

Response format

On this page

Error body

Order of checks

Are you charged?

Error codes

Authentication and permissions

Credits and billing

Plans and subscriptions

Validation (all endpoints)

Rate and quota limits

Data store and live fetch

Free tools

Rank tracking

Issues, indexing and AI visibility

Site audit and project context

Google Search Console

Google Ads keyword research

IndexNow

Approval inbox and agent tasks

Outreach

LinkedIn automation (Zeekeo)

Handling errors

Which errors to retry

Code samples

Related