Rate Limits

Audience

This API surface is for integration partners building on top of the Rokt network. Rokt ecommerce partners integrating placements on their own checkout should use the Rokt Ecommerce developer docs instead.

The Partnerships API caps requests per minute on a small set of write-heavy and recovery endpoints. Limits are keyed to your partner principal (derived from your API token), not to your IP — so multiple servers in your fleet share one bucket.

Limits by endpoint

Method & Path	Limit	Rationale
POST /v1/accounts/register/partnership	10 / minute	Registration kicks off a multi-step backend orchestration — expensive, and merchant-onboarding traffic is bursty rather than sustained.
POST /v1/partnership/accounts/{account_id}/payout-setup	10 / minute	Each call provisions a Stripe Connect account.
POST /v1/partnership/network-privacy-requests	10 / minute	Consumer privacy request traffic should be paced and submitted once per user request.
POST /v1/partnership/accounts/{account_id}/data-deletion-requests	10 / minute	Account-level deletion submits to the Data Deletion service and is tracked as a partnership operation.
POST /v1/partnership/accounts/{account_id}/pages	30 / minute	Add-page provisioning is heavier than a controls write; lower cap than MCL/status.
PUT /v1/partnership/accounts/{account_id}/pages/{page_id}	30 / minute	Layout-type switching is page provisioning work — same weight class and cap as add-page.
PATCH /v1/partnership/accounts/{account_id}/layouts/{layout_id}	60 / minute	Theme PATCH writes the templated layout configuration.
PUT /v1/partnership/accounts/{account_id}/marketplacecontrolslists	60 / minute	Per-merchant control writes; comfortable headroom for batch sync.
PUT /v1/partnership/accounts/{account_id}/offercontrolslists	60 / minute	Per-merchant offer-side control writes.
PUT /v1/partnership/accounts/{account_id}/status	60 / minute	Pause/resume cascade across page variants.
GET /v1/partnership/operations/{operation_id}	600 / minute	Polling-friendly. Sized for ~10 polls/sec across your whole fleet.
Other read endpoints (GET /v1/partnership/accounts, MCL, OCL, status, payout-status, blocked-domains)	60 / minute	Per-partner default for partnership reads.

備考

Limits are per partner, not per merchant. If you onboard 50 merchants in a minute, you'll hit the register limit on the 11th call regardless of which merchant it's for. Spread bursts out, or queue client-side.

注記

POST /v1/partnership/network-privacy-requests does not take Idempotency-Key and does not create a partnership operation. For that endpoint, honor Retry-After and retry only the same user request after backoff. Account-level data deletion uses the normal Idempotency-Key retry contract.

How limits are keyed

Limits are keyed to your API credentials. Every server in your fleet using the same credentials shares one counter.

Requests with a missing, invalid, or unverifiable Authorization header are rejected with 401 before rate-limiting applies.

The 429 response

When a limit is exceeded, the server returns 429 Too Many Requests with the standard partnership envelope:

{
  "status": 429,
  "error": "RateLimitExceeded",
  "message": "Rate limit exceeded: 10 per 1 minute. Retry after the window resets.",
  "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
  "data": null
}

Response headers

A 429 response carries:

Retry-Afterinteger

Seconds until the next call will be accepted. Honor this — it's the cheapest signal you have.

Backoff guidance

1. 1
   Honor Retry-After first

   On a 429, sleep for the Retry-After value before any retry. It's already computed from your remaining window — there's no benefit to retrying sooner, and retries inside the window count toward your quota.

2. 2
   Use the same Idempotency-Key on retry

   For POST and PUT calls, retry with the same Idempotency-Key you used on the rejected call, inside the 24-hour dedup window. Rate-limit rejections don't execute server-side, so the cached response will be the eventual success — not a stale 429.

3. 3
   Cap concurrency client-side

   Queue client-side and respect Retry-After — pre-empting the limit is cheaper than reacting to it.

4. 4
   Polling — pace your operation reads

   The 600/min limit on operation polling is sized for one poll every ~100ms across your whole fleet. If you're polling tighter than that, you're paying egress cost for no information — operations don't transition that fast. Recommended: poll every 2-5 seconds with exponential backoff up to 60 seconds.

警告

Do not retry on a fresh Idempotency-Key after a 429. The original call did not execute, but if you later send a different key for the same logical write, the server has no way to dedup — and you may end up with duplicate state if a subsequent retry succeeds twice for different reasons.

What's not rate-limited (today)

GET endpoints other than operation polling — including controls reads, status reads, and payout-status reads — are not rate-limited today. This may change. Treat the absence of a documented limit as "currently uncapped" rather than "guaranteed uncapped."

When you genuinely need higher limits

The current ceilings are sized for steady-state merchant onboarding traffic. If your launch plan calls for a sustained spike (e.g. backfilling 10,000 merchants in a single migration window), email smb-partnerships@rokt.com with the endpoint, the expected RPS, and the duration window. We can raise your partner principal's cap in advance without a code change on your side.

Related

• Errors — full status-code reference, including 429's place in the envelope
• Idempotency — how the dedup window interacts with retries
• Handling Failures — broader retry policy across all error classes