Rate limits

Limits are counted per key, separately for reads and writes.

Your plan may grant higher values, and an individual key can be raised separately — the actual budget is always in the response headers, so trust those rather than the numbers in this table.

Headers

Every response carries the state of the current window:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1786000860

• X-RateLimit-Limit — the budget for this kind of request (read or write).
• X-RateLimit-Remaining — requests left in the current minute.
• X-RateLimit-Reset — Unix seconds at which the next window starts.

The window is fixed, not sliding: the counter resets at the start of each minute.

When you run out

Per-minute limit exceeded — 429 with Retry-After: 60:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded",
    "requestId": "5f6c…"
  }
}

Daily write quota exhausted — also 429, but with a different code and a Retry-After that runs to the end of the day:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Daily write quota exceeded",
    "requestId": "5f6c…"
  }
}

Tell them apart by code: rate_limited clears within a minute, quota_exceeded not until the next day — retrying sooner is pointless.

How to behave

• Read the headers instead of hunting for the error. When X-RateLimit-Remaining approaches zero, slow down on your side.
• Honour Retry-After. It is an exact time to the next window, not a hint.
• Use exponential backoff with jitter so parallel workers do not all come back at once.
• Do not poll the exchange in a loop. For "what changed" there is updatedSince (Pagination and sync); for "something appeared on my lane" there are webhooks. Both are cheaper than polling.
• Batch your creates. One POST /proposals/batch with up to 25 items saves the per-minute budget (though it does consume 25 units of the daily quota — see Examples).