Skip to main content
The Raise API allows 1,500 requests per hour by default. Raise counts requests separately for each authenticated caller (such as an API key) in each organization, in fixed one-hour windows that start on the hour (UTC). This page covers how the limit is counted, the headers Raise returns, what a 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, including 429 responses:

The 429 response

When a caller goes over the limit, Raise returns 429 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.
The 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

Read X-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
For steady background work such as nightly syncs, spread requests across the hour. 1,500 requests per hour averages out to 25 requests per minute.

Handle 429 with Retry-After

When a 429 arrives, wait for the number of seconds in Retry-After, then retry:
JavaScript
Because the window is fixed, 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 replace endpoints (PUT /api/Campaign/replace, PUT /api/Project/replace, PUT /api/Segment/replace) handle replacement operations in a single call.
  • The Query endpoints return more results per call than the equivalent looped reads would.
There is no general bulk-write endpoint for Gifts or Donors. Bulk operations on those resources are loops at the integration level, with throttling applied per request.

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.
Last modified on November 3, 2026