Rate Limits

Overview

Rate limits control the number of API requests your application can make within a specific time. These limits are allocated at the account level and help maintain system stability while ensuring fair resource allocation.

Rate limit tiers

Sandbox environment

• Rate Limit: 10 requests per second (TPS)
• Daily Quota: 1,000 requests per day
• Purpose: Development, testing, and integration validation
• Billing: Free tier included with all accounts

Production environment

• Initial State: 0 TPS (all requests blocked)
• Activation: Requires approval and configuration
• Purpose: Live production traffic
• Custom Limits: Tailored to your specific use case and volume requirements

📘

Production Access Required:

Production accounts start with rate limits disabled (0 TPS) as a safety measure. Contact Socure Support to activate your production environment with appropriate limits.

Requesting production access

Contact Socure Support with the following information:

• Expected request volume (TPS and daily totals)
• Peak usage patterns and time periods
• Integration timeline and go-live date

Socure evaluates your request and updates your production limits to an approved throughput level.

Rate limits and subaccounts

Rate limits are allocated at the account level, not per individual API key. All API keys that belong to the same account — including the keys used by its subaccounts — draw from a single shared rate limit allocation.

This means issuing a separate API key for each subaccount does not give each subaccount its own throughput. Whether your subaccounts share one API key or each use their own key, their requests count against the same account-level limit.

📘

Multi-subaccount deployments:

Adding subaccounts or generating additional API keys doesn't automatically increase your rate limit allocation. If you need a higher combined limit — or a dedicated allocation for a specific subaccount — contact Socure Support to review and adjust your limits. This helps high-throughput subaccounts avoid 429 errors.

Rate limit response headers

RiskOS™ returns rate limit headers on every API response, enabling your application to monitor usage and implement proactive throttling.

Headers on all responses

Additional header on 429 responses

📘

Proactive throttling:

Use the X-RateLimit-Remaining-Day and X-RateLimit-Remaining-Window headers to monitor your usage in real time. By tracking remaining capacity, your application can slow down or queue requests before hitting the limit — avoiding 429 errors entirely.

Handling rate limit exceeded

HTTP 429 response

When you exceed your rate limit, the API returns a 429 Too Many Requests status:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded for this resource"
}

All 429 responses include an X-Retry-After header that specifies how many seconds to wait before retrying. The response also includes the standard rate limit headers:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit-Day: 1000
X-RateLimit-Limit-Window: 10
X-RateLimit-Remaining-Day: 0
X-RateLimit-Remaining-Window: 0
X-Retry-After: 2

Exponential backoff

To prevent retry storms and ensure smooth recovery from rate limits or transient errors, implement exponential backoff with jitter.

Exponential backoff spaces out retries and randomizes delays to avoid simultaneous retry spikes across multiple clients.

Recommended pattern

When receiving a 429 or 5xx error:

1. Read the X-Retry-After header (if present) and wait that many seconds.
2. If the header is missing, retry using exponential backoff:
   • Start with a 1–2 second delay.
   • Double the delay after each retry (2s, 4s, 8s, 16s...).
   • Add a random "jitter" (±1s) to avoid retry collisions.
   • Stop after about 5 attempts or 1 minute.

Example implementation of exponential backoff with jitter:

import time, random

def retry_with_backoff(request_fn, max_attempts=5):
    for attempt in range(max_attempts):
        response = request_fn()
        if response.status_code not in (429, 500, 503):
            return response
        wait = (2 ** attempt) + random.uniform(0, 1)
        print(f"Rate limited. Retrying in {wait:.2f} seconds...")
        time.sleep(wait)
    raise Exception("Max retries exceeded")

Best practices

• Always respect X-Retry-After when provided — it overrides your local delay.
• Don't retry indefinitely; cap retries and log rate-limit events.
• Queue non-urgent requests to smooth burst traffic.
• Use idempotency keys to safely retry without duplicating requests.