Rate limits
Understand organization throughput pools, response headers, and how to build resilient retry logic across Marvin2, Platform API v1, and Risk API v2.
How limits work
Relativity6 enforces rate limits to keep latency predictable for every organization:
- Shared per organization, isolated by environment: Production keys (
r6-...) share your organization's live throughput pool. Test keys (r6-test-...) use a separate test pool so integration suites and CI pipelines never consume or contend with live underwriting capacity. See Environments. - Sustained rate + short burst: Each endpoint group enforces both a sustained requests per minute limit and a short requests per second burst ceiling so normal concurrency succeeds while tight retry loops are smoothed.
- Polling is isolated from submissions: Status polling (
GET /v2/risk/{job_id},GET /v1/assessments/{id}) uses dedicated high-throughput read pools so checking job progress never competes with submitting new assessments. - Throttled requests are never billed: Requests rejected with
429 RATE_LIMIT_EXCEEDEDor429 MAX_CONCURRENT_JOBS_EXCEEDEDdo not consume request quotas or Risk API v2 credits.
Rate limits vs. quotas and credits
Rate limits govern how fast requests arrive (RATE_LIMIT_EXCEEDED, safe to retry after Retry-After). Contractual allowances govern total usage over your billing period (QUOTA_EXCEEDED on v1/Marvin2 or 402 INSUFFICIENT_CREDITS on Risk API v2 — do not retry until your balance resets or is topped up).
Default service limits
Default limits apply automatically based on your account tier and key environment unless your organization has custom throughput terms configured.
| Product & group | Endpoints | Production default | Test & trial default |
|---|---|---|---|
| Marvin2 APIIndustry classification & co-tenant | POST /marvin2, POST /classification, POST /co-tenant | 120 req/min10 req/sec burst | 30 req/min3 req/sec burst |
| Platform API v1Business risk & flags | POST /v1/business/risk, POST /v1/flags | 20 req/min4 req/sec burst | 10 req/min2 req/sec burst |
| Platform API v1Assessment status & reads | GET /v1/assessments/{id} | 300 req/min20 req/sec burst | 120 req/min10 req/sec burst |
| Risk API v2BetaJob submission & snapshot extend | POST /v2/risk, POST /v2/snapshots/{id}/extend | 15 req/min5 req/sec burst · 10 active jobs | 5 req/min2 req/sec burst · 3 active jobs |
| Risk API v2BetaJob polling, entities & webhooks | GET /v2/risk/{job_id}, POST /v2/risk/{job_id}/cancel, /v2/webhooks | 600 req/min25 req/sec burst | 180 req/min10 req/sec burst |
On Risk API v2 (POST /v2/risk), active jobs counts jobs currently in queued or running status for that environment. Once a job reaches completed or failed (or is cancelled via POST /v2/risk/{job_id}/cancel), its slot is released immediately.
Response headers
Authenticated API responses include standard HTTP Structured Fields rate-limit headers so your client can pace requests proactively before reaching a limit:
| Header | Description |
|---|---|
RateLimit-Policy | Policy configuration for the matched endpoint group — sustained per-minute quota (q, w=60) and burst capacity (w=1). Example: "marvin2:classify";q=120;w=60, "marvin2:classify:burst";q=10;w=1 |
RateLimit | Remaining requests (r) in the active sustained window and seconds until the window resets (t). Example: "marvin2:classify";r=94;t=38 |
Retry-After | Included on 429 responses. Number of whole seconds to wait before sending the next request. When both Retry-After and RateLimit are present, always honor Retry-After. |
Handling 429 responses
When your organization exceeds a burst, per-minute, or concurrent-job ceiling, the API returns HTTP 429 Too Many Requests with Retry-After and a structured JSON body:
429 — Request rate limit exceeded
429 — Active Risk API v2 job limit reached
Recommended client practices:
- Honor
Retry-Afterwith jitter: Read theRetry-Afterheader (orretry_after_secondsin the JSON body) and add a small random jitter (100–500 ms) so parallel workers do not wake at the exact same instant. - Check the error
codebefore retrying: RetryRATE_LIMIT_EXCEEDEDandMAX_CONCURRENT_JOBS_EXCEEDED. Do not retryQUOTA_EXCEEDEDor402 INSUFFICIENT_CREDITSin a loop. - Send
Idempotency-KeyonPOST /v2/risk: Safe retries with the sameIdempotency-Keyattach to the original submission if it already succeeded. - Use webhooks or 2–3s polling for Risk API v2: Registering webhooks eliminates polling loops altogether; when polling
GET /v2/risk/{job_id}, a 2–3 second interval with?after={cursor}stays well inside the read pool.
Requesting higher limits
Need higher sustained throughput for portfolio batch runs, high-concurrency underwriting workflows, or dedicated per-key sub-caps for third-party integrations? Relativity6 can configure custom per-organization and per-API-key limits on your account.