429 Too Many Requests response looks like, and the patterns that keep an integration under the limit.
How the limit is counted
Requests made while you are limited don’t extend the window. A client that keeps retrying through a
429 still recovers when the window ends.
Because the limit is counted per caller and organization, a partner integration that holds one API key for each customer organization gets a separate budget for each of those organizations.
Rate-limit headers
Raise adds three headers to API responses, including429 responses:
The 429 response
When a caller goes over the limit, Raise returns429 Too Many Requests with the three rate-limit headers and a Retry-After header. Retry-After is the number of seconds until the window ends.
429 body is the plain-text message Rate limit exceeded., not the ProblemDetails JSON envelope that other Raise errors use. Check the status code before you parse the body as JSON.
Handling the limit
Slow down before you hit the limit
ReadX-RateLimit-Remaining on each response. When it reaches zero, pause until the time in X-RateLimit-Reset instead of sending requests that will be rejected:
JavaScript
Handle 429 with Retry-After
When a 429 arrives, wait for the number of seconds in Retry-After, then retry:
JavaScript
Retry-After can be up to an hour. For interactive requests, surface the delay instead of blocking a user for that long. For background jobs, schedule the remaining work for after X-RateLimit-Reset.
Stop hammering on persistent 429s
If an integration hits the limit every hour, its traffic is larger than the budget. Treat it as an operational signal: find the workflow that consumes the most requests and apply the patterns below. See Error Recovery Patterns: Circuit breakers for the full pattern.Patterns that reduce rate-limit pressure
Four patterns reduce the rate at which an integration consumes API budget:Use the largest Take value the endpoint supports
Each request to a /list or /query endpoint consumes one rate-limit slot regardless of how many records it returns. A Take=1000 request returns 1,000 records for the cost of one request; a Take=25 request returns 25 records for the same cost. For bulk reads, use the maximum.
See Pagination and Filtering.
Cache reference data
Endpoints that return reference data —GET /api/CustomField/List, GET /api/Premium/list, GET /api/Project/list, GET /api/Campaign/list — change rarely. Cache the results at integration startup and refresh on a slow cadence (daily is fine for most reference data).
Prefer webhooks over polling
For change detection on Donors, Gifts, and RecurringGifts, subscribe to webhook events instead of polling/api/Donor/list?SortBy=modifieddatetimeutc repeatedly. Webhooks deliver changes within seconds and don’t consume the API rate-limit budget for change detection. See Webhooks Overview.
Batch where the API supports it
The Raise API exposes a few patterns that reduce request count for related operations:- The
replaceendpoints (PUT /api/Campaign/replace,PUT /api/Project/replace,PUT /api/Segment/replace) handle replacement operations in a single call. - The
Queryendpoints return more results per call than the equivalent looped reads would.
Where to go next
Pagination and Filtering
Use the largest
Take and the right query pattern to minimize request count.Error Recovery Patterns
Retry strategies, circuit breakers, and dead-letter handling.
API Performance Tips
Caching, batching, and other patterns that reduce rate-limit pressure.
Error Handling
The
ProblemDetails envelope that other Raise errors use.