# Limits and retries

> Calls per minute, request size caps, the request form B7R accepts, and how to retry with Retry-After and backoff.

Source: https://docs.b7r.app/limits-and-retries

## Calls per minute

Each account has a limit of calls per minute, shared by all its keys: more keys never raise it. The limit is an account setting, so read it from `limits.calls_per_minute` in [`GET /v1/me`](https://docs.b7r.app/keys-and-access#read-your-account-and-key) instead of writing it into your code. Separate caps per address and per key protect the API from floods.

Over a limit, the answer is `429 rate_limited` with a `Retry-After` header in seconds. A `429` means nothing changed and nothing was charged: wait that long, then send the same request again.

## Request size

| Part | Cap |
| --- | --- |
| Path | 512 characters |
| Query string | 1024 characters |
| Body | 262144 bytes (256 KiB) |

A body over its cap answers `413 request_too_large`. A path or query over its cap is refused with a `4xx` problem whose `retryable` is `false`.

## The form of a request

The API reads requests in one exact form, so that nothing can be read two ways. HTTP clients send this form by default.

- Paths exactly as in the reference: no trailing `/`, no `//`, no `.` or `..` segments, no `%` encoding.
- Query keys are lowercase letters, digits and `_`; values are letters, digits and `.`, `_`, `~`, `:`, `-`. Each key once.
- A GET has no body. A POST sends JSON with `Content-Type: application/json` (`; charset=utf-8` is fine) and no `Content-Encoding`.
- A path outside the API answers `404 not_found`, a known path with the wrong method `405 method_not_allowed`, another content type `415 unsupported_media_type`, and anything else out of form `400 invalid_request`.

## When to retry

Every error carries `retryable`. Retry only when it is `true`: that is `429` and the `5xx` codes. A `4xx` with `retryable: false` fails the same way every time until you change the request.

- Honour `Retry-After` when it is present.
- Otherwise back off: about 1, 2, 4 and 8 seconds, each with some randomness, and stop after 5 attempts.
- Retry a POST with the same `Idempotency-Key` and the same body. See [Safe retries](https://docs.b7r.app/safe-retries).
- Set a client timeout of about 30 seconds. The API answers or gives up with `504 upstream_timeout` before that.

Retry with backoff:

```javascript
async function callB7r(url, options = {}, attempts = 5) {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(url, { ...options, signal: AbortSignal.timeout(30_000) });
    if (res.ok) return res.json();
    const problem = await res.json();
    if (!problem.retryable || attempt === attempts) throw Object.assign(new Error(problem.title), { problem });
    const retryAfter = Number(res.headers.get("retry-after"));
    const backoff = 2 ** (attempt - 1) * 1000 * (0.5 + Math.random());
    await new Promise((r) => setTimeout(r, retryAfter > 0 ? retryAfter * 1000 : backoff));
  }
}
```

```python
import random, time, requests

def call_b7r(method, url, attempts=5, **kwargs):
    for attempt in range(1, attempts + 1):
        res = requests.request(method, url, timeout=30, **kwargs)
        if res.ok:
            return res.json()
        problem = res.json()
        if not problem.get("retryable") or attempt == attempts:
            raise RuntimeError(f"{problem['code']}: {problem['title']}")
        retry_after = int(res.headers.get("Retry-After", "0") or 0)
        time.sleep(retry_after or 2 ** (attempt - 1) * (0.5 + random.random()))
```
