Rate Limits & Retries

API requests are rate-limited per API key. This page documents the headers you get back, what a 429 looks like, and how to back off correctly. The official SDK handles all of this for you automatically.

Response headers

Every API response carries your current rate-limit state:

Read X-RateLimit-Remaining to throttle proactively before you hit the limit. Limits scale with your plan — see your capabilities.limits via GET /api/v1/whoami.

When you exceed the limit — 429

A throttled request returns 429 Too Many Requests with the standard error envelope and a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 3
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1750077600
Content-Type: application/json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. You have exceeded your rate limit.",
    "status": 429,
    "retryable": true,
    "request_id": "req_...",
    "docs_url": "https://docs.viucraft.com/api/errors#rate_limit_exceeded"
  }
}

How to retry

1. Honor Retry-After — wait that many seconds before retrying. If it's absent, fall back to X-RateLimit-Reset.
2. Back off exponentially for repeated 429s (e.g. 1s, 2s, 4s, 8s) with a little jitter.
3. Only retry idempotent calls automatically (GET, DELETE, delivery). Be careful auto-retrying POST /upload — check whether the first attempt actually succeeded (a duplicate upload returns 200 with the existing image_id, so retrying is safe here).

Let the SDK do it

The official viucraft SDK retries 429s automatically, honoring Retry-After with exponential backoff — you don't write any of the above:

const client = new ViucraftClient({
  apiKey,
  subdomain,
  retry: { maxRetries: 3 },   // on by default; honors Retry-After
});

When a request ultimately fails, the SDK throws a ViucraftRateLimitError carrying retryAfter and the requestId (quote it to support). The CLI surfaces the same on its errors.