UMW API Rate Limits, Tiers, and Retry Handling Guide

UMW enforces per-organization rate limits on all API endpoints to ensure platform stability and fair access for every integration. Limits are applied using a sliding one-minute window and are tracked independently per organization — not per API key. Understanding your limit tier, monitoring the rate limit headers on every response, and implementing proper retry logic are essential steps for building a production-grade integration.

Rate Limit Tiers

Your organization’s limit tier is determined at account provisioning. Contact your UMW account manager if you need to discuss an upgrade.

Tier	Requests per Minute	Burst Limit
Standard	120 req/min	30 requests
Enterprise	600 req/min	100 requests

The burst limit represents the maximum number of requests that can be sent in any single second before the platform begins returning 429 responses, even if you have remaining quota in the broader one-minute window. Design your client to spread requests evenly rather than issuing them all simultaneously.

Rate Limit Response Headers

The UMW API returns rate limit metadata on every response, including successful ones. Inspect these headers proactively to throttle your client before a 429 occurs.

Header	Type	Description
`RateLimit-Limit`	integer	The total number of requests your organization is allowed within the current window (reflects your tier’s requests-per-minute value).
`RateLimit-Remaining`	integer	The number of requests remaining in the current window. When this reaches `0`, the next request will receive a `429` response.
`RateLimit-Reset`	integer (Unix timestamp)	The UTC Unix timestamp at which the current window expires and your quota resets to the full limit.
`Retry-After`	integer (seconds)	Returned only on `429` responses. Indicates the number of seconds your client must wait before sending another request.

Sample Response Headers

HTTP/1.1 200 OK
RateLimit-Limit: 120
RateLimit-Remaining: 87
RateLimit-Reset: 1718460000
Content-Type: application/json

When your request is rejected:

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 1718460060
Retry-After: 42
Content-Type: application/json

Handling 429 Responses

When you receive a 429 Too Many Requests response, your client should pause for the number of seconds specified in the Retry-After header before retrying the request. For robustness against transient spikes, implement exponential backoff with jitter — this prevents multiple clients from resuming simultaneously and causing a follow-on burst. The following Python example demonstrates a safe retry pattern:

import time
import random
import httpx

MAX_RETRIES = 5
BASE_DELAY_SECONDS = 1.0

def api_request_with_retry(method: str, url: str, **kwargs) -> httpx.Response:
    """
    Wraps an HTTPX request with exponential backoff on 429 responses.
    Honors the Retry-After header when present.
    """
    for attempt in range(MAX_RETRIES):
        response = httpx.request(method, url, **kwargs)

        if response.status_code != 429:
            # Raise for any other non-2xx status; caller handles application errors
            response.raise_for_status()
            return response

        retry_after = response.headers.get("Retry-After")
        if retry_after:
            wait = float(retry_after)
        else:
            # Exponential backoff: 1s, 2s, 4s, 8s, 16s ...
            wait = BASE_DELAY_SECONDS * (2 ** attempt)

        # Add jitter (±20%) to prevent thundering-herd effect
        jitter = wait * 0.2 * (random.random() * 2 - 1)
        sleep_for = max(0, wait + jitter)

        print(f"Rate limited. Retrying in {sleep_for:.2f}s (attempt {attempt + 1}/{MAX_RETRIES})")
        time.sleep(sleep_for)

    raise RuntimeError(f"Request failed after {MAX_RETRIES} retries due to rate limiting.")

Best Practices

Following these guidelines will help you stay well within your rate limit allowance and build a more resilient integration.

Batch requests where possible. Several UMW endpoints accept arrays of items in a single request. For example, rather than creating ten tracks with ten separate POST /v1/tracks calls, use the bulk track creation endpoint to submit all tracks in one request.
Cache GET responses. Catalog metadata, territory lists, and store configurations change infrequently. Cache GET responses locally with a reasonable TTL (e.g., 5–15 minutes) to avoid redundant read requests that consume quota without producing new information.
Use webhooks instead of polling. Polling GET /v1/deliveries/{id} or GET /v1/assets/{id} in a tight loop is one of the most common causes of unnecessary rate limit consumption. Subscribe to the corresponding webhook events (delivery.completed, asset.ready, etc.) and let the UMW platform push status updates to your endpoint instead.
Monitor RateLimit-Remaining proactively. Instrument your HTTP client to log or alert when RateLimit-Remaining falls below 20% of RateLimit-Limit. Reacting before you hit 0 avoids any disruption to time-sensitive workflows.
Serialize non-critical writes. If your workflow involves bulk ingestion (e.g., importing a back-catalog), introduce deliberate delays between requests during off-peak hours rather than saturating your quota all at once.

The UMW sandbox environment operates under relaxed rate limits designed to support rapid development and testing. Requests made to https://sandbox-api.umwrecordingsinc.com do not count toward your production rate limit quota. Always validate retry and backoff logic against the sandbox before deploying to production.

Get Started

Platform Guides

Platform Reference

UMW API Rate Limits, Tiers, and Retry Handling Guide

Rate Limit Tiers

Rate Limit Response Headers

Sample Response Headers

Handling 429 Responses

Best Practices

​Rate Limit Tiers

​Rate Limit Response Headers

​Sample Response Headers

​Handling 429 Responses

​Best Practices

Rate Limit Tiers

Rate Limit Response Headers

Sample Response Headers

Handling 429 Responses

Best Practices