API usage, rate limits, and errors

Reliable Rankability integrations treat pooled usage, request-rate limits, crawler quotas, job concurrency, and provider availability as separate controls.

Resolve the active usage contract

Before consequential on-demand work, request:

curl https://app.rankability.com/api/agent/v1/usage \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

Full-platform accounts return product_mode: "full_platform" and metering_model: "pooled_usage". The response includes the connected organization (id and name), general 7-day and burst 24-hour remaining percentages, recovery timestamps, scheduled-work protection, and the Billing usage path. It does not expose internal units, credit balances, or per-action prices.

Copywriter Core returns metering_model: "outcome_allowances" with its separate completed-outcome allowances.

Estimate usage impact

Use the read-only estimator before approval:

curl "https://app.rankability.com/api/agent/v1/usage/estimate?operation=site_audit_run&max_pages=500" \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

The response describes impact as standard or high and identifies on-demand usage. It does not start work. For Tracker, include project_id so the estimate can account for the saved keywords, platforms, locations, and Local Pack grid.

Pooled limits

If an on-demand window is exhausted, a run endpoint returns 429 usage_limit_reached with window, retry_at, and usage_path. Respect the recovery time and do not fan out retries. Scheduled tracking and monitoring are not blocked by these on-demand windows.

Request-rate limits

Each API key, and each MCP connection, has a per-minute request limit over a sliding 60-second window. MCP tool calls count against the same limit as direct API calls.

Product	Plan	Requests per minute, per key	Requests per day
Rankability	Starter, Agency and Agency Pro (including trials), and every earlier Rankability plan	60	No daily cap
Rankability	Free	30	No daily cap
Copywriter plans	Core	30	No daily cap
Copywriter plans	Scale	60	No daily cap
Copywriter plans	High-volume	120	No daily cap
SEO Researcher	Free sample and Starter	60	No daily cap
SEO Researcher	Pro	120	No daily cap
SEO Researcher	Agency	240	No daily cap
SEO Researcher	Scale	500	No daily cap

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A request-rate failure returns 429 rate_limit_exceeded with Retry-After. Respect Retry-After and treat X-RateLimit-Limit as authoritative rather than hard-coding a value.

Crawler quotas

Scrape and Crawl can also have a daily page quota. Check /api/agent/v1/crawler/usage and read X-Quota-Limit, X-Quota-Used, and X-Quota-Remaining. A crawler quota failure returns 429 quota_exceeded. This is separate from pooled usage and request-rate limiting.

Structured errors

Agent API errors include an error code, message, and optional details. Log X-Request-Id, method, route, status, and time. Never log Bearer tokens or sensitive request bodies.

HTTP	Common code	Meaning
400	invalid_input, validation_error	Missing, malformed, unsafe, or unsupported input
401	unauthorized	Missing or invalid authentication
403	forbidden, plan_limit_exceeded, subscription_required	Missing scope, unavailable capability, or a lapsed account
404	not_found	Resource not found in the authenticated organization
409	conflict, selfserve_ai_query_limit, selfserve_google_keyword_limit	A job is running, the resource is in the wrong state, or a new Tracker project would exceed a self-serve tracking allowance
422	validation_error	Structured payload failed validation
429	usage_limit_reached, rate_limit_exceeded, quota_exceeded, capacity_reached	A rolling usage, request, or crawler window is temporarily limited, or Tracker is too busy to start a scan
500	internal_error	Unexpected server failure
502	provider or operation unavailable	Required service was unavailable
503	queue_unavailable, service_unavailable	The work could not be queued; retry shortly
504	operation timeout	Synchronous work exceeded its time budget

Retry safely

• Retry reads and polling with bounded exponential backoff and jitter.
• For 429, follow Retry-After or retry_at and distinguish pooled usage from request or crawler limits.
• For 502, 503, and 504, retry later with a bounded attempt count.
• Do not retry validation, authentication, permission, or not-found errors until their cause changes.
• On 409, use the returned state or existing job ID instead of creating duplicate work.
• Send a stable idempotency key on supported create calls and store returned operation IDs before polling.

See Getting started with the API and Connecting Rankability to AI assistants with MCP.