Rate limits

The Diversity Sync API limits how many requests you can make in a given window so that no single integration can degrade the service for everyone. Every /v1 response tells you exactly where you stand, and going over the limit returns a 429 you can recover from cleanly.

Limits are applied per credential, not per request — see the table below. Stay under them by reading the RateLimit-* headers on each response rather than guessing, and always honour Retry-After when you do get throttled.

Limits

Name
/v1 resource endpoints
Type
120 requests / minute
Description
Counted per API key. Every key gets its own budget, so isolating workloads behind separate keys gives each one a full allowance.
Name
POST /oauth/token
Type
30 requests / minute
Description
Counted per source IP, because token requests are unauthenticated until the key is validated. Cache the access token you receive and reuse it for its full 15‑minute lifetime instead of minting a new one per request.

RateLimit headers

Every /v1 response carries three headers describing your current budget. Read them on each response so you can slow down before you hit the limit rather than reacting to a 429.

Name
RateLimit-Limit
Type
integer
Description
The maximum number of requests permitted in the current window (e.g. 120).
Name
RateLimit-Remaining
Type
integer
Description
The number of requests left in the current window. When this reaches 0, the next request is rejected with 429.
Name
RateLimit-Reset
Type
integer
Description
The number of seconds until the window resets and RateLimit-Remaining is replenished.

Each response also includes the standard Request-Id and Diversity-Sync-Version: v1 headers — quote the Request-Id if you contact support about a throttled request.

RateLimit headers on a 200 response

HTTP/1.1 200 OK
Diversity-Sync-Version: v1
Request-Id: req_8f2c1d9a4b7e
RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 41

Exceeding the limit

When you exceed your budget the API responds with 429 Too Many Requests and a Retry-After header telling you how many seconds to wait. The RateLimit-* headers are still present, and RateLimit-Remaining will be 0.

The two endpoints differ only in the body they return:

/v1 resource endpoints return the standard error object with a type of rate_limit_error and a code of rate_limited.
POST /oauth/token keeps its RFC 6749 shape and returns an error of slow_down with a human-readable error_description.

Wait for the period indicated by Retry-After, then retry. We recommend an exponential backoff with jitter on top of Retry-After so a fleet of clients doesn't retry in lockstep.

Retry-After is the authoritative signal — prefer it over RateLimit-Reset for deciding when to retry, and never retry a 429 immediately.

A 429 from a /v1 endpoint

HTTP/1.1 429 Too Many Requests
Diversity-Sync-Version: v1
Request-Id: req_3b6e0c71f29d
Retry-After: 12
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 12
Content-Type: application/json

Response — /v1 error object

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Retry after 12 seconds.",
    "doc_url": "https://docs.diversitysync.com/errors#rate_limited",
    "request_id": "req_3b6e0c71f29d"
  }
}

Response — POST /oauth/token (RFC 6749)

{
  "error": "slow_down",
  "error_description": "Too many token requests from this IP. Retry after 12 seconds.",
  "request_id": "req_3b6e0c71f29d"
}

Staying under the limit

A few habits keep well-behaved integrations clear of the limit:

Reuse access tokens. Exchange your ds_live_… key once, then reuse the access token for its full 15-minute life rather than calling /oauth/token per request.
Watch RateLimit-Remaining. Throttle yourself client-side as it approaches 0 instead of waiting for a 429.
Honour Retry-After. Back off for at least the stated number of seconds, then add exponential backoff with jitter for repeated 429s.
Page efficiently. Request up to limit=100 per call and iterate with starting_after so a full export costs as few requests as possible.