Build resilient clients with explicit handling for auth, balance, rate limits, and server errors.

​
Common errors

StatusMeaningSuggested action
400Bad requestValidate payload and types
401Invalid API keyFix Authorization header
402Insufficient balanceAdd credits, pre-check balance
413Payload too largeReduce file size or duration
429Rate limit exceededBackoff and retry
500Server errorRetry with exponential backoff

​
Request with retries

import time
import requests

def request_with_retries(method, url, headers=None, **kwargs):
    """Basic retry policy with 429 and transient 5xx handling."""
    backoff = 1.0
    for attempt in range(5):
        try:
            r = requests.request(method, url, headers=headers, timeout=60, **kwargs)
            if r.status_code == 429:
                # Rate limit
                time.sleep(backoff)
                backoff = min(backoff * 2, 30)
                continue
            if 500 <= r.status_code < 600:
                # Transient server error
                time.sleep(backoff)
                backoff = min(backoff * 2, 30)
                continue
            # Non-retry path
            r.raise_for_status()
            return r
        except requests.exceptions.RequestException as e:
            if attempt == 4:
                raise
            time.sleep(backoff)
            backoff = min(backoff * 2, 30)

    raise RuntimeError("Unreachable")

# Example usage
API_KEY = "sk-your-api-key-here"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
url = "https://tryvinci.com/api/v1/generate/text-to-video"
data = {"prompt": "Calm ocean at sunrise", "duration_seconds": 5}

resp = request_with_retries("POST", url, headers=headers, json=data)
print(resp.json())

​
Handle known statuses

import requests

def handle_known_statuses(r: requests.Response):
    if r.status_code == 401:
        raise PermissionError("Invalid API key. Check Authorization header.")
    if r.status_code == 402:
        detail = r.json().get("detail")
        raise RuntimeError(f"Insufficient balance: {detail}")
    if r.status_code == 413:
        raise ValueError("File too large. Reduce the payload size.")
    if r.status_code == 429:
        raise RuntimeError("Rate limit exceeded. Retry with backoff.")

# Example
API_KEY = "sk-your-api-key-here"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
url = "https://tryvinci.com/api/v1/generate/text-to-video"
data = {"prompt": "Forest in fog", "duration_seconds": 5}

r = requests.post(url, headers=headers, json=data)
if not r.ok:
    handle_known_statuses(r)
r.raise_for_status()
print(r.json())

​
Recommendations

  • Always include Authorization header on every request.
  • Pre-check balance before costly jobs (see Billing & Usage).
  • Use exponential backoff and cap max retries.
  • Log request_id from creation responses to trace jobs.