GovDash
Menu

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.

BudgetReads per minuteWrites per minute
Per key600120
Per team3,000600
  • GET requests are reads. POST, PATCH, and DELETE are 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,members counts as three reads. Repeating a field doesn't count twice.
  • GET /openapi.json isn'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.

HeaderValue
x-ratelimit-limitRequests per minute allowed by that budget.
x-ratelimit-remainingRequests left in that budget.
x-ratelimit-resetSeconds until that budget is completely refilled.
HTTP/1.1 200 OK
x-ratelimit-limit: 600
x-ratelimit-remaining: 598
x-ratelimit-reset: 1

The 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.bucketWhat happenedWhat to do
tokenThis key used up its budget.Slow down this integration.
teamYour 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

  1. Watch x-ratelimit-remaining. When it gets low, slow down before you hit 429.
  2. On 429, wait at least retry-after seconds, then retry.
  3. If you get 429 again, 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.

retry-on-429.tsTypeScript
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))
  }
}
retry_on_429.pyPython
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_since to 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.