Relativity6Platform Docs

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_EXCEEDED or 429 MAX_CONCURRENT_JOBS_EXCEEDED do 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 & groupEndpointsProduction defaultTest & trial default
Marvin2 APIIndustry classification & co-tenantPOST /marvin2, POST /classification, POST /co-tenant120 req/min10 req/sec burst30 req/min3 req/sec burst
Platform API v1Business risk & flagsPOST /v1/business/risk, POST /v1/flags20 req/min4 req/sec burst10 req/min2 req/sec burst
Platform API v1Assessment status & readsGET /v1/assessments/{id}300 req/min20 req/sec burst120 req/min10 req/sec burst
Risk API v2BetaJob submission & snapshot extendPOST /v2/risk, POST /v2/snapshots/{id}/extend15 req/min5 req/sec burst · 10 active jobs5 req/min2 req/sec burst · 3 active jobs
Risk API v2BetaJob polling, entities & webhooksGET /v2/risk/{job_id}, POST /v2/risk/{job_id}/cancel, /v2/webhooks600 req/min25 req/sec burst180 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:

HeaderDescription
RateLimit-PolicyPolicy 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
RateLimitRemaining requests (r) in the active sustained window and seconds until the window resets (t). Example: "marvin2:classify";r=94;t=38
Retry-AfterIncluded 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-After with jitter: Read the Retry-After header (or retry_after_seconds in 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 code before retrying: Retry RATE_LIMIT_EXCEEDED and MAX_CONCURRENT_JOBS_EXCEEDED. Do not retry QUOTA_EXCEEDED or 402 INSUFFICIENT_CREDITS in a loop.
  • Send Idempotency-Key on POST /v2/risk: Safe retries with the same Idempotency-Key attach 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.

See data you like? Contact us to get access.
Your Relativity6 team can add response sections, risk profiles, and usage capacity to match how you want to underwrite. Tell us which capabilities you want to enable and we will align your account with your agreement.