> ## Documentation Index
> Fetch the complete documentation index at: https://learn.biq.li/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> Understand Biqli workspace API quotas, response fields, and safe retry behavior.

Biqli applies a fixed one-minute request quota to protect API availability and
ensure fair use. The exact allowance is determined by the workspace's current
plan and is returned with successful responses and rate-limit rejections.

All workspace API keys for the same workspace share this allowance. Creating
additional keys does not create additional quota.

## IETF RateLimit fields

The Biqli workspace API follows the
[IETF HTTPAPI RateLimit header fields Internet-Draft](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers)
and returns its structured `RateLimit-Policy` and `RateLimit` fields on
successful responses and rate-limit rejections.

<Note>
  The cited specification is an active Internet-Draft and may evolve. Biqli
  implements its current `RateLimit-Policy` and `RateLimit` field format.
</Note>

| Field              | Meaning                                                                    |
| :----------------- | :------------------------------------------------------------------------- |
| `RateLimit-Policy` | Identifies the policy, total quota, and window size.                       |
| `RateLimit`        | Reports the remaining quota and effective window for the current response. |
| `Retry-After`      | On a `429` response, the number of seconds to wait before retrying.        |

A successful response can include:

```http theme={null}
RateLimit-Policy: "workspace-api";q=1000;w=60
RateLimit: "workspace-api";r=999;t=58
```

The structured parameters mean:

| Parameter | Meaning                                                       |
| :-------- | :------------------------------------------------------------ |
| `q`       | Requests allocated to the workspace during the policy window. |
| `w`       | Policy window length in seconds. Biqli uses `60`.             |
| `r`       | Requests currently remaining after this request.              |
| `t`       | Seconds remaining in the effective window.                    |

The policy name is `workspace-api`. Biqli does not expose its internal
workspace partition key in response fields.

<Warning>
  A positive `r` value is quota guidance, not a guarantee that a future request
  will succeed. Requests can still fail because of permissions, validation,
  resource quotas, or temporary service conditions.
</Warning>

## Legacy compatibility fields

Biqli also returns the existing `X-RateLimit-*` fields so integrations using
them continue to work:

| Field                   | Meaning                                             |
| :---------------------- | :-------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests in the current one-minute window.  |
| `X-RateLimit-Remaining` | Requests remaining after the current request.       |
| `X-RateLimit-Reset`     | On a `429`, the reset time as a UTC Unix timestamp. |

Build new integrations against `RateLimit-Policy`, `RateLimit`, and
`Retry-After`. The `X-RateLimit-*` fields are compatibility aliases rather
than the current IETF structured format.

## When the limit is exceeded

When the shared workspace allowance is exhausted, Biqli returns
`429 Too Many Requests`:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
RateLimit-Policy: "workspace-api";q=1000;w=60
RateLimit: "workspace-api";r=0;t=17
Retry-After: 17
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1788126519
X-Biq-Request-Id: ae437f49-30a3-4d55-bca6-dc523f2efcb3
```

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Slow down! You're moving a bit too fast. Please wait a few seconds before trying again."
  },
  "request_id": "ae437f49-30a3-4d55-bca6-dc523f2efcb3"
}
```

If both `Retry-After` and `RateLimit` are present, follow `Retry-After`.

## Retry safely

<Steps>
  <Step title="Stop sending requests">
    Pause requests for the affected workspace when the API returns `429`.
  </Step>

  <Step title="Honor Retry-After">
    Wait at least the number of seconds in `Retry-After`. Add a small random
    delay when many workers could retry simultaneously.
  </Step>

  <Step title="Retry deliberately">
    Retry only the failed operation. Use an idempotent `external_id` where the
    endpoint supports it so a network retry does not create a duplicate.
  </Step>
</Steps>

For transient network errors or `5xx` responses, use exponential backoff with
jitter and a maximum retry count. Do not retry authentication, permission, or
validation failures as though they were rate-limit failures.

## Use the allowance efficiently

* Use [Bulk create links](/docs/api-reference/links/bulk-create),
  [Bulk update links](/docs/api-reference/links/bulk-update), and
  [Bulk delete links](/docs/api-reference/links/bulk-delete) for large jobs.
* Request the largest appropriate `page_size` and follow cursor pagination
  instead of repeatedly fetching the first page.
* Cache resource data that does not need to be refreshed on every operation.
* Use `RateLimit` proactively and slow workers before `r` reaches zero.
* Coordinate concurrent workers because every key in the workspace consumes
  the same quota.

## Request limits versus resource quotas

Rate limits control request frequency and return `429 rate_limit_exceeded`.
They are separate from plan resource quotas, such as the number of links or QR
codes a workspace may create. A resource quota or unavailable feature normally
returns a `403` error such as `quota_exceeded` or `upgrade_required`.

Treat every attempted request as potentially consuming quota, including a
request that later fails validation. The response fields are the source of
truth for the workspace's currently effective request allowance; do not
hardcode a plan limit in your integration.

For handling non-rate-limit failures, see [Errors](/docs/api-reference/errors).