Rate limits
GovDash limits how many requests you can make per minute so one integration can't slow down the API for everyone else. If you go over a limit, you get a 429 response. This page lists the limits, the headers that report your usage, and how to stay well under them.
Limits
Each request counts against two budgets at once: one for the API key that made it, and one for the key's team. Reads and writes have separate budgets.
| Budget | Reads per minute | Writes per minute |
|---|---|---|
| Per key | 600 | 120 |
| Per team | 3,000 | 600 |
GETrequests are reads.POST,PATCH, andDELETEare writes.- All of a team's keys share the per-team budget. Five keys on one team still get 3,000 reads a minute in total.
- Each field you request with
expand[]counts as one more request against both budgets.GET /v1/opportunities?expand[]=custom_fields,memberscounts as three reads. Repeating a field doesn't count twice. GET /openapi.jsonisn't rate limited.
The budgets refill continuously rather than resetting at the top of each minute. A rejected request doesn't use up any budget.
Headers
Every response from a rate-limited endpoint, successful or not, includes these headers. They describe whichever budget is closest to running out.
| Header | Value |
|---|---|
x-ratelimit-limit | Requests per minute allowed by that budget. |
x-ratelimit-remaining | Requests left in that budget. |
x-ratelimit-reset | Seconds until that budget is completely refilled. |
HTTP/1.1 200 OK
x-ratelimit-limit: 600
x-ratelimit-remaining: 598
x-ratelimit-reset: 1The 429 response
When a budget runs out, the API returns 429 with a retry-after header in seconds. error.bucket tells you which budget ran out.
GovDash also returns 429 when one address sends too many requests with keys it doesn't accept. That response has only retry-after, without the x-ratelimit-* headers or error.bucket.
HTTP/1.1 429 Too Many Requests
retry-after: 1
x-ratelimit-limit: 120
x-ratelimit-remaining: 0
x-ratelimit-reset: 60
content-type: application/json
{
"error": {
"code": "rate_limited",
"message": "This access token exceeded its write rate limit.",
"bucket": "token"
}
}error.bucket | What happened | What to do |
|---|---|---|
token | This key used up its budget. | Slow down this integration. |
team | Your team used up its budget. | Other integrations on your team share this budget. Slow down, or spread work over time. |
Requests with a bad API key are limited too. If a client keeps sending one, it gets 429 with no bucket, even for requests that use a good key. Fix or remove the bad key, then wait retry-after seconds.
Handle rate limiting
- Watch
x-ratelimit-remaining. When it gets low, slow down before you hit429. - On
429, wait at leastretry-afterseconds, then retry. - If you get
429again, wait longer each time. Double the delay and add random jitter so parallel workers don't retry in lockstep.
A rejected request has no effect, so retrying a 429 is always safe, including for writes.
async function withRateLimitRetry(
request: () => Promise<Response>,
maxAttempts = 5,
): Promise<Response> {
for (let attempt = 1; ; attempt++) {
const response = await request()
if (response.status !== 429 || attempt === maxAttempts) {
return response
}
const retryAfter = Number(response.headers.get("retry-after") ?? "1")
const backoff = retryAfter * 2 ** (attempt - 1)
const jitter = Math.random() * 1000
await new Promise((resolve) => setTimeout(resolve, backoff * 1000 + jitter))
}
}import random
import time
def with_rate_limit_retry(request, max_attempts=5):
for attempt in range(1, max_attempts + 1):
response = request()
if response.status_code != 429 or attempt == max_attempts:
return response
retry_after = float(response.headers.get("retry-after", "1"))
time.sleep(retry_after * 2 ** (attempt - 1) + random.random())Stay under the limits
Most integrations never come close to these limits. The ones that do are usually re-reading data that hasn't changed.
- Sync incrementally. Pass
updated_sinceto list only the opportunities, contracts, companies, agencies, people, documents, or agent runs that changed since your last run. See Sync incrementally. - Cache values that rarely change. Phases and custom field definitions from
/v1/meta/*change rarely. Read them once per run, not before every write. - Spread out bulk work. If you're loading a large backlog, run it at a steady pace rather than in one burst.
Need more?
If you're hitting rate limits regularly, tell us at [email protected]. Sometimes it's a sign that a different approach would be faster and cheaper for you, and we're happy to help work out what that is. Sometimes your scale just needs more than these limits allow, and we want to hear about that too.