Rate limits and retries

Pace requests, handle throttling, and resume safely without duplicating writes.

Rate limits keep the Core API responsive for everyone. An integration should control how quickly it sends requests and slow down when the API asks it to wait.

Provisional limit: 500 requests per second. This figure is pending confirmation by Brella. Confirm the production quota and how it is shared across tokens and IP addresses before planning a high-volume import. Treat this as a ceiling, not a target throughput.

When a request is throttled

The API returns 429 Too Many Requests. Check the HTTP status before assuming the body is JSON: rate limiting happens before the Core controller, and a throttled response may have a plain-text body.

Read the Retry-After response header. For example:

HTTP/1.1 429 Too Many Requests
Retry-After: 2

This illustrative value means wait at least two seconds before retrying. Use the actual header value, not a fixed two-second delay. Retry-After can express either a delay in seconds or an HTTP date; see the HTTP specification.

A practical retry policy

Pause the shared request queue on 429. Slowing down just one worker does not help if other workers keep sending through the same token or IP address.
Honor Retry-After when present. Add a small random delay afterward so multiple workers do not all restart together. Do not shorten a server-specified wait to fit a local retry cap.
Use exponential backoff if the header is missing or invalid. For example, wait 1, 2, 4, then 8 seconds, with a little random variation and a maximum fallback delay of 30 seconds. These are suggested client settings, not API limits.
Bound the retries. After a small number of attempts, such as five, pause the job and report the failure. Save progress so it can resume from the failed item.
Resume at a lower pace. A successful retry is not a signal to immediately return to the same burst that caused throttling.

Keep normal traffic below the limit

Use a queue with a small, bounded number of concurrent requests. Spread traffic across time instead of launching a large batch at once.
Coordinate the budget across jobs sharing a token or outbound IP. Creating more tokens or rotating IP addresses is not a rate-limit strategy.
Fetch pages instead of one record at a time. The default page size is 30 and the maximum is 100; use a suitable size for the data you need.
Where a resource supports them, use date filters for incremental synchronization. The scope must allow those query fields. Use include for permitted related data instead of a separate request for every related record.
Reuse already-fetched IDs and unchanged data. Save the last completed page or item so a restart does not repeat the entire import.
Track request volume, 429 responses, wait times, and failures without logging tokens. Persistent throttling after slowing down is a reason to contact Brella with the affected time window and request context.

Retry writes carefully

An explicit 429 from the API’s rate limiter rejects that attempt before the Core action runs. Retry it after the required delay.

A timeout, disconnected connection, or 5xx response is different: the client may not know whether a write finished. Before replaying a create or an update with side effects, read back the relevant record and reconcile what was applied. Keep the returned Brella IDs and any supported external identifiers in your import log so a retry does not create duplicates.

Do not retry 400, 403, 404, or 422 in a tight loop. Fix the request, token/scope, target record, or validation problem first. See Responses and errors and the integration checklist.