Rate limits & idempotency

Rate limits

Limits are per API key:

Scope	Limit	Why
All requests	120 / minute	General ceiling.
Census writes (`PUT /census`, `POST`/`PATCH` members, `POST /elections`)	20 / minute	Census writes fan out to rating and (post-enrollment) live records. Batch with `PUT /census` instead of looping `POST /members`.
Quote creates (`POST /groups/{groupId}/quotes`, `POST /quotes`, and the MCP tools that call them)	60 / hour	Quotes are persistent records; don’t use them as a pricing calculator in a loop. A `409 rates_pending` doesn’t count, so polling while the market comparison runs is safe.

Exceeding a limit returns 429 rate_limited with a Retry-After header (seconds):

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "error": "rate_limited", "message": "Too many requests. Please retry later." }

Honor Retry-After rather than guessing your own backoff; it reflects the actual window. These limits are sized for steady-state integrations (a nightly full-roster sync for hundreds of employers fits comfortably); if a bulk migration needs more, ask your partner engineer for a temporary raise rather than building a throttle dance. Failed authentication is throttled separately: requests with a missing, malformed, revoked, or unknown API key are limited to 30 attempts per minute per source IP, after which the API returns 429 rate_limited instead of 401. Authenticated traffic is unaffected by this limiter. If you see it during development, check that your key is loaded correctly rather than retrying.

Idempotency

These endpoints accept an Idempotency-Key header:

Endpoint
`POST /groups`	Create a group
`PUT /groups/{groupId}/census`	Replace the census
`POST /groups/{groupId}/members`	Add a member
`POST /groups/{groupId}/quotes`	Create a quote
`POST /quotes`	Quote a census in one call (a `202` pricing status is never stored)
`POST /groups/{groupId}/elections`	Submit elections
`POST /groups/{groupId}/enrollments`	Create an enrollment
`PUT /webhook`	Set your webhook URL

Other writes ignore the header: PATCH /groups/{groupId}, PATCH /groups/{groupId}/members/{memberId}, POST /embed-sessions (mint a fresh session on every open anyway), POST /webhook/test, and POST /events/{eventId}/redeliver.

curl -X POST https://www.getprescience.com/api/partner/v1/groups/grp_8c2f41d09a3e/enrollments \
  -H "Authorization: Bearer $PRESCIENCE_API_KEY" \
  -H "Idempotency-Key: enroll-acme-1" \
  -H "Content-Type: application/json" \
  -d '{ "quoteId": "qt_5b9e2c7f10ad", "signatory": { "name": "Dana Park", "email": "dana@acme.com" } }'

Semantics:

24-hour replay window. Repeating the same key with the same body within 24 hours returns the stored response (same status and body) without re-executing anything. Replays carry an Idempotent-Replay: true header.
Scoped to the key, the body, the endpoint, and the mode. A replay needs the same key, the same JSON body, the same method and path, and a key of the same mode. The same key with a different body runs as a new request.
Only successful responses are stored. Errors returned before or during the write (validation failures, 409, 410, 5xx) are not stored, so a corrected retry runs normally under the same key. A PUT /census response that reports per-row errors is a 200 and is stored.
Replays of PUT /webhook return the stored body, including the signing secret from the original call. A new key rotates the secret.
Key is free-form. Any non-empty string. Deterministic keys derived from your own entity IDs (enroll-{companyId}-{quoteId}) work better than random UUIDs, because retries after a process crash regenerate the same key.
Scoped to your partner account. No cross-partner collisions.

Use it on every call that creates something an employer will see, especially POST /groups and POST /enrollments. A timeout is not a failure; the request may have landed. With an idempotency key, the retry answers that question safely.

Get Started

Guides

Brokers

Resources

Rate limits

Idempotency

​Rate limits

​Idempotency

Rate limits

Idempotency