> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-credits-rate-limits-and-errors.md).

# 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:

```bash
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 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:

```bash
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 headers

Read `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` rather than hard-coding a plan value. A request-rate failure returns `429 rate_limit_exceeded`; respect `Retry-After`.

## 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`                             | Missing scope or unavailable capability                            |
| `404` | `not_found`                                                    | Resource not found in the authenticated organization               |
| `409` | `conflict`                                                     | A job is running or the resource is in the wrong state             |
| `422` | `validation_error`                                             | Structured payload failed validation                               |
| `429` | `usage_limit_reached`, `rate_limit_exceeded`, `quota_exceeded` | A rolling usage, request, or crawler window is temporarily limited |
| `500` | `internal_error`                                               | Unexpected server failure                                          |
| `502` | provider or operation unavailable                              | Required service was unavailable                                   |
| `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` 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](/api/api-getting-started.md) and [Connecting Rankability to AI assistants with MCP](/api/mcp-getting-started.md).