OpusClip API 429 Too Many Requests and the monthly API cap

clipsdk limits from our limits docs and pricing.

Source: OpusClip API limits, checked 7 November 2026

1. 1

   Tell the three answers apart

   A 429 without X-Cap-Reason means the key sent more than 30 requests in a minute. A 429 with X-Cap-Reason: concurrent means 4 projects are already running, or 50 on Business. A 403 with code: API_MONTHLY_CAP_REACHED means the workspace used its 900 credits this month.

2. 2

   Pace every request to one per 2 seconds

   30 a minute is one request every 2 seconds. Share one pacer across every worker and every polling loop that uses the key, since they all draw from the same 30.

3. 3

   Keep at most 4 projects running

   Count the projects you have in flight and free a slot when one finishes, from your webhook or your poll. A fifth project then waits for a slot instead of collecting 429s.

4. 4

   Back off on 429, with jitter

   Wait 2 seconds and double the wait on every try, up to 60, plus up to 1 second of jitter so workers don't retry in step. On concurrent, start at 15 seconds. OpusClip doesn't document Retry-After, so the code only uses it when a response carries it.

   import os
   import random
   import threading
   import time
   
   import requests
   
   API = os.environ.get("OPUS_API", "https://api.opus.pro/api")
   KEY = os.environ["OPUS_API_KEY"]
   MAX_TRIES = 6
   
   
   class MonthlyCapReached(Exception):
       def __init__(self, body):
           super().__init__(f"OpusClip API cap reached until {body['reset_at']}")
           self.reset_at = body["reset_at"]
           self.upgrade_url = body["upgrade_url"]
   
   
   class Pacer:
       # 30 requests a minute per key is one every 2 s, shared by every thread
       def __init__(self, per_minute):
           self.gap = 60 / per_minute
           self.next_at = 0.0
           self.lock = threading.Lock()
   
       def wait(self):
           with self.lock:
               now = time.monotonic()
               at = max(now, self.next_at)
               self.next_at = at + self.gap
           time.sleep(at - now)
   
   
   pacer = Pacer(30)
   started = time.monotonic()
   
   
   def backoff(attempt, reason, retry_after):
       # OpusClip doesn't document Retry-After, so we only use it when it shows up
       if retry_after and retry_after.isdigit():
           return float(retry_after)
       base = 15.0 if reason == "concurrent" else 2.0
       return min(60.0, base * 2**attempt) + random.uniform(0, 1)
   
   
   def create_project(video_url):
       for attempt in range(MAX_TRIES):
           pacer.wait()
           response = requests.post(
               f"{API}/clip-projects",
               headers={"Authorization": f"Bearer {KEY}"},
               json={"videoUrl": video_url},
               timeout=30,
           )
   
           # The monthly cap is a 403, not a 429: no retry helps before reset_at
           is_json = response.headers.get("Content-Type", "").startswith("application/json")
           if response.status_code == 403 and is_json and response.json().get("code") == "API_MONTHLY_CAP_REACHED":
               raise MonthlyCapReached(response.json())
   
           if response.status_code != 429:
               response.raise_for_status()
               return response.json()
   
           reason = response.headers.get("X-Cap-Reason", "rate")
           seconds = backoff(attempt, reason, response.headers.get("Retry-After"))
           print(f"{time.monotonic() - started:5.1f} s  429 ({reason}), try {attempt + 2} in {seconds:.1f} s")
           time.sleep(seconds)
   
       raise RuntimeError(f"still 429 after {MAX_TRIES} tries")
   
   
   if __name__ == "__main__":
       for _ in range(2):
           try:
               create_project("https://api.clipsdk.com/f/lib/demo/rocket-ranch-podcast.mp4")
               print(f"{time.monotonic() - started:5.1f} s  200, project created")
           except MonthlyCapReached as cap:
               print(f"{time.monotonic() - started:5.1f} s  403 API_MONTHLY_CAP_REACHED, paused until {cap.reset_at}")

5. 5

   Stop on 403 API_MONTHLY_CAP_REACHED

   Don't retry it: nothing changes before reset_at. Park the work until then, upgrade through upgrade_url, or send the overflow to another API. We ran the script against a local stub that answers the way OpusClip's limits page documents: two 429s, a 429 with X-Cap-Reason: concurrent, a 200, then the 403.

   $ python opus_retry.py
     0.0 s  429 (rate), try 2 in 2.4 s
     2.5 s  429 (rate), try 3 in 4.4 s
     6.8 s  429 (concurrent), try 4 in 60.7 s
    67.5 s  200, project created
    69.5 s  403 API_MONTHLY_CAP_REACHED, paused until 2026-12-01T00:00:00Z