Rate limits and errors

Every /v2 request draws from your organization's token bucket, and every token request draws from a stricter bucket for its key. An empty bucket returns 429 with Retry-After. Every error from a /v2 endpoint, whatever its status, is one JSON envelope with a stable code to branch on and a request_id to send to Brellium support.

Rate limits

Limits

Live and sandbox requests draw from separate buckets with the same limits (Test with a sandbox key). The token limit is per key, so a sandbox key and a live key never share that bucket either. That limit is tight because a token lasts about a day: mint one token per key and reuse it (Authenticate with OAuth2 client credentials).

The token bucket

Each bucket starts full, and every authenticated request takes one token, whether it ends in 200, 400 or 404. Tokens come back continuously at the refill rate, up to the burst capacity, so there is no fixed reset time. A request passes when at least one whole token is available. A short spike is fine, and steady traffic settles at the refill rate. These limits are maximums; Brellium does not guarantee you can always reach them.

Headers

Every authenticated /v2 response and every POST /v2/oauth/token response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A 429 adds Retry-After.

A 401 from a /v2 endpoint carries no RateLimit-* headers and does not count against the limit.

A 429 response

When your organization's bucket is empty, a list request such as this one returns a 429.

curl --include "https://api.brellium.com/v2/audits?status=complete&limit=100" \
  --header "Authorization: Bearer $BRELLIUM_ACCESS_TOKEN"

const params = new URLSearchParams({ status: "complete", limit: "100" });
const res = await fetch(`https://api.brellium.com/v2/audits?${params}`, {
  headers: { Authorization: `Bearer ${process.env.BRELLIUM_ACCESS_TOKEN}` },
});
// Like curl --include: the status and headers, then the body.
console.log(res.status, res.statusText);
for (const [name, value] of res.headers) console.log(`${name}: ${value}`);
console.log(await res.json());

import BrelliumClient, { APIError } from "@brellium/api-client";

const client = new BrelliumClient({ oAuth2: process.env.BRELLIUM_ACCESS_TOKEN });

try {
  // maxRetries: 0 shows the 429; by default the client waits Retry-After and
  // retries.
  const { data, response } = await client.audits
    .list({ status: "complete", limit: 100 }, { maxRetries: 0 })
    .withResponse();
  console.log(response.status, response.headers.get("RateLimit-Remaining"));
  console.log(data);
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.status, err.headers?.get("Retry-After"), err.error);
  }
  throw err;
}

import os

from brellium_api_client import APIStatusError, BrelliumClient

client = BrelliumClient(o_auth2=os.environ["BRELLIUM_ACCESS_TOKEN"])

try:
    # max_retries=0 shows the 429; by default the client waits Retry-After and
    # retries.
    raw = client.with_options(max_retries=0).audits.with_raw_response.list(
        status="complete", limit=100
    )
    print(raw.status_code, raw.headers.get("RateLimit-Remaining"))
    print(raw.parse().to_json())
except APIStatusError as err:
    print(err.status_code, err.response.headers.get("Retry-After"), err.body)
    raise

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
x-request-id: 7f0b3c1e-2a4d-4b8e-9c11-5d6e7f8a9b0c
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1
Retry-After: 1

The body is the envelope with type rate_limit_error and code RATE_LIMITED. A 429 from POST /v2/oauth/token has the same type and code with its own message, listed in Every code.

Retry a 429

Apply these rules to every 429:

1. When Retry-After is present, wait that many seconds plus a short random delay, then retry the same request. The delay (up to 500 ms in the samples) keeps processes that share your organization's rate limit from retrying at the same moment.
2. When Retry-After is absent, back off exponentially with jitter (1 s, 2 s, 4 s, 8 s, capped at 30 s). Treat a 500 or 502 the same way.
3. Cap the attempts and the total time, then report the error. After a 5xx on a write you don't know whether the write happened, so fetch the record before you write again.

Retry only idempotent reads (GET) automatically. A 400 fails the same way every time, a 401 fails until you mint a new token, and a retry sent before Retry-After has passed can get another 429. These samples wrap the GET from the 429 example in a retry loop and print the status, RateLimit-Remaining and x-request-id.

// Keep credentials on the server; never in a browser or mobile app.
const BASE_URL = "https://api.brellium.com";
const TOKEN = process.env.BRELLIUM_ACCESS_TOKEN;

const MAX_ATTEMPTS = 5;
const MAX_TOTAL_MS = 60_000;

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

// Retries idempotent reads only: 429 and 5xx, never 400 or 401.
export async function getWithRetry(path: string): Promise<Response> {
  const started = Date.now();
  let attempt = 0;
  while (true) {
    attempt += 1;
    const res = await fetch(`${BASE_URL}${path}`, {
      headers: { Authorization: `Bearer ${TOKEN}` },
    });
    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || attempt >= MAX_ATTEMPTS) return res;

    const retryAfter = Number(res.headers.get("Retry-After") ?? 0);
    const backoffMs = Math.min(30_000, 1_000 * 2 ** (attempt - 1));
    const jitterMs = Math.random() * 500;
    const waitMs =
      retryAfter > 0 ? retryAfter * 1_000 + jitterMs : backoffMs + jitterMs;

    if (Date.now() - started + waitMs > MAX_TOTAL_MS) return res;
    await sleep(waitMs);
  }
}

async function main(): Promise<void> {
  const res = await getWithRetry("/v2/audits?status=complete&limit=100");
  console.log(
    res.status,
    res.headers.get("RateLimit-Remaining"),
    res.headers.get("x-request-id"),
  );
}

main();

# Keep credentials on the server; never in a browser or mobile app.
import os
import random
import time

import requests

BASE_URL = "https://api.brellium.com"
TOKEN = os.environ["BRELLIUM_ACCESS_TOKEN"]

MAX_ATTEMPTS = 5
MAX_TOTAL_SECONDS = 60.0


def get_with_retry(path: str) -> requests.Response:
    """Retries idempotent reads only: 429 and 5xx, never 400 or 401."""
    started = time.monotonic()
    attempt = 0
    while True:
        attempt += 1
        res = requests.get(
            f"{BASE_URL}{path}",
            headers={"Authorization": f"Bearer {TOKEN}"},
            timeout=30,
        )
        retryable = res.status_code == 429 or res.status_code >= 500
        if not retryable or attempt >= MAX_ATTEMPTS:
            return res

        retry_after = float(res.headers.get("Retry-After") or 0)
        backoff = min(30.0, 2.0 ** (attempt - 1))
        jitter = random.uniform(0, 0.5)
        wait = retry_after + jitter if retry_after > 0 else backoff + jitter

        if time.monotonic() - started + wait > MAX_TOTAL_SECONDS:
            return res
        time.sleep(wait)


res = get_with_retry("/v2/audits?status=complete&limit=100")
print(
    res.status_code,
    res.headers.get("RateLimit-Remaining"),
    res.headers.get("x-request-id"),
)

For a complete request wrapper with pacing and capped backoff, see Handle rate limits and retries. For token caching and the re-mint on 401, see Mint one access token and reuse it.

Stay under the limit

These habits keep your traffic under both limits:

• Mint one token per key, cache it for its expires_in, and share it with every process that uses that key.
• Filter in the request with status=, set_id=, documents= or updated_after= so you fetch fewer pages (Page through and filter lists).
• Ask for limit=100. A backfill of 10,000 audits takes 100 requests at limit=100 and 500 at the default of 20.
• Sync with updated_after instead of fetching every audit again (Keep audits in sync with updated_after).
• Watch RateLimit-Remaining and slow down as it approaches 0 instead of waiting for the 429.

Responses without an envelope

A bare 403, 413, 414 or 431 has no JSON body and no x-request-id. A 413, 414 or 431 means the body, the URL or the headers were too large.

A 403 with a JSON body and the code MTLS_REQUIRED, MTLS_CERTIFICATE_MISMATCH or MTLS_POLICY_UNAVAILABLE comes from the mutual TLS check (Mutual TLS). Any other 403 on a /v2 request is bare. The causes of a bare one are too many requests from one IP address in a short time, a query string over 2,048 bytes, and a request refused for security reasons. In a batch get, 2,048 bytes hold about 44 audit_id values, so split larger batches (Page through and filter lists).

Errors

The envelope

Every error from a /v2 endpoint is one JSON envelope:

{
  "error": {
    "type": "not_found_error",
    "code": "NOT_FOUND",
    "message": "Audit not found",
    "request_id": "7f0b3c1e-2a4d-4b8e-9c11-5d6e7f8a9b0c"
  }
}

POST /v2/oauth/token uses this envelope only for RATE_LIMITED and BAD_GATEWAY. Any other error from it, such as access_denied for a wrong secret or an unknown client_id, comes in the OAuth error format instead of this envelope (Authenticate with OAuth2 client credentials).

Status, type and cause

Every code

Each operation in the API reference lists the statuses it can return, except 500. A zip that can't be unpacked is not an HTTP error: the document's status becomes extraction_failed with an ARCHIVE_* code in metadata.archive.error (Upload documents).

The batch update endpoints, POST /v2/audits/batch_update and POST /v2/users/batch_update, return 200 and report each failed item in place as { "audit_id": ..., "error": {...} } or { "user_id": ..., "error": {...} }, so check every item. Audit items fail with NOT_FOUND or INTERNAL_ERROR. User items can also fail with the 409 codes of PATCH /v2/users/{user_id}: USER_EXISTS, or EMAIL_RECIPIENT_EXISTS with param email.

Common validation errors

Each VALIDATION_ERROR carries the failing field in details[].path and its message in details[].message. These are the errors you are most likely to hit:

• Too big: expected number to be <=100, path ["limit"]: a limit over 100 is a 400, not a page of 100. Send limit=100 and page with starting_after.
• Invalid ISO datetime, path ["created_after"] (or updated_after, created_before, updated_before): send an RFC 3339 timestamp in UTC ending in Z, such as 2026-09-24T02:37:12Z. A date alone or a time with an offset is rejected.
• Invalid UUID, path ["audit_id"]: the path id is not a UUID, so nothing is looked up. A well-formed unknown id returns 404 NOT_FOUND, and a well-formed cursor that matches nothing returns an empty 200 page.
• Email addresses at brellium.com can't be added as users. (or ... as email recipients.), path ["email"] (["items", 0, "email"] in a batch update): every write to a user or an email recipient rejects an email at brellium.com or its subdomains. The envelope's message is the same text, and param is email.
• content_type must be one of ..., path ["documents", 0, "content_type"]: every document on POST /v2/documents needs a content_type from the accepted list, and the file name's extension does not count. The same endpoint returns external_id values must be unique within a request and a zip must be the only document in the request (Upload documents).
• Malformed JSON in request body, code HTTP_ERROR: the body has a trailing comma or a missing quote, or Content-Type: application/json came with no body. This error has no details. Any other content type, or none, is rejected first with 400 INVALID_CONTENT_TYPE.
• Sending starting_after and ending_before together is not an error. The API uses only one of them, so an unexpected page can mean you sent both.
• flags must be unique, path ["flags"], on PATCH /v2/audits/{audit_id}: the list has the same flag twice. It replaces the audit's flags and holds up to 50 unique, non-empty strings (Update audit flags).

Request ids

The same id appears in the x-request-id header on every response and in error.request_id on every error, and Brellium support uses it to find the request. If you send your own X-Request-Id, the API returns it; otherwise the API generates a UUID.

Log the id with every call. Send Brellium support the request_id (also the x-request-id response header) and the time of the request. Leave response bodies out of the report: they can contain protected health information (PHI).

Next