Overview

Rate limits control the number of API requests your application can make within a specific time period. These limits are enforced per API key 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

Our team will evaluate your request based and update production limits to an approved throughput level.

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",
  "message": "Too many requests, slow down"
}

All 429 responses include a Retry-After header that specifies how many seconds to wait before retrying:

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

Exponential backoff

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

This approach spaces out retries and randomizes delays to avoid simultaneous retry spikes across multiple clients.

Recommended pattern

When receiving a 429 or 5xx error:

Read the Retry-After header (if present) and wait that many seconds.
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 Retry-After when provided — it overrides your local delay.
Do not 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.