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 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-8is fine) and noContent-Encoding. - A path outside the API answers
404 not_found, a known path with the wrong method405 method_not_allowed, another content type415 unsupported_media_type, and anything else out of form400 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-Afterwhen 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-Keyand the same body. See Safe retries. - Set a client timeout of about 30 seconds. The API answers or gives up with
504 upstream_timeoutbefore that.
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));
}
}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()))