Rate limits

Which limit hits you, what every operation costs and how your client waits after a 429. GET /v1/rate_limit returns your own state.

Cost per operation

Every call takes points from the bucket. The reference shows the value at every operation as x-bodo-cost; no endpoint is free.

get · 1
list · 2
count · 2
search q · +5
create · 5
update · 5
delete · 10
money action · 10
long run (202) · 10
batch · sum of its parts
me · 1
rate_limit · 1
openapi.json · 1
operations · events · 1

Levels

The answer always reports the tightest limit.

Level	Applies to	Limit
Key	one key	300 points/min, capacity 600
Writes	one key	60 writes/min
Concurrency	one key	6 concurrent calls
Principal	all keys of a person or a service account	1,200 points/min
Organization	all keys of the organization	3,000 points/min, one key at most 50 %
Deletes	one key	10/min and 300 per day, then deleting is paused
Data outflow	one key	10,000 records read/h

Headers

Following the IETF draft RateLimit header fields (draft 11). Every answer carries both lines.

A normal answer, then the rejection

RateLimit-Policy: "key";q=300;w=60, "org";q=3000;w=60
RateLimit: "key";r=12;t=41

HTTP/1.1 429 Too Many Requests
Retry-After: 41
RateLimit: "key";r=0;t=41

Example response

GET /v1/contacts?limit=100

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://developers.bodo-app.com/problems/RATE_LIMITED",
  "title": "Too many requests",
  "status": 429,
  "detail": "The limit of this key is reached.",
  "instance": "/v1/contacts",
  "code": "RATE_LIMITED",
  "requestId": "req_01JBD8Y3K5M7Q2W9X4Z6T1V0NP"
}

Three kinds of 429

Code	Meaning	Reaction
RATE_LIMITED	your limit is reached	wait for `Retry-After`
OVERLOADED	the instance is busy	wait for `Retry-After`, then add jitter
QUOTA_EXHAUSTED	a quota is used up	do not retry until it resets

Throttling never answers 403. Quota alert: when a quota runs low or the outflow is unusually high, the owner of the key and the organization admins get an email and an entry in the bell.

Backoff

Whoever keeps firing after a 429 (more than 50 rejections in 60 s) gets the key locked for 5 minutes.

Read Retry-After (whole seconds) or, more precisely, retryAfterMs from the problem.
Wait that long and add a little random jitter, so not all clients come back at once.
Without the header, double the wait per attempt (1, 2, 4, 8 s) and give up after five attempts.
Do not retry QUOTA_EXHAUSTED: the answer stays the same until the reset.

The SDKs wait for you@bodo/api and bodo-api retry a 429 or 503 after Retry-After, by default up to twice (maxRetries or max_retries), with the same idempotency key.