PicX Studio

Rate Limits

How tier-based rate limits, the daily credit cap, and 429 responses work.

View as Markdown

Rate limits protect the API and keep usage fair. They are applied per API key and are tier-based: your tier determines the exact per-minute and per-day request limits, the concurrency limit, and the daily credit cap.

Because limits depend on your tier, read your current values from the tier endpoint rather than hardcoding numbers.

GET /v1/account/tier

Return the current rate limits and quotas for your account. Authenticated with your API key — usable from backend services, CI jobs, and agents without a browser session.

Auth: API Key (Bearer token)

FieldTypeDescription
plan_codestringCurrent tier name (e.g. "pro").
requests_per_minuteintegerMax requests per rolling minute window.
requests_per_dayintegerMax requests per calendar day (UTC).
concurrent_limitintegerMax in-flight requests at once.
max_credits_per_dayintegerDaily credit spending cap. Resets 00:00 UTC.
allowed_model_typesstring[]Model categories this tier can access.
curl https://api.picxstudio.com/v1/account/tier \
  -H "Authorization: Bearer pxsk_your_key"
{
  "plan_code": "pro",
  "requests_per_minute": 60,
  "requests_per_day": 10000,
  "concurrent_limit": 10,
  "max_credits_per_day": 13000,
  "allowed_model_types": ["image", "video", "audio", "agent"]
}

Call this once at startup and cache it. Tier limits rarely change mid-session.

GET /api/tier (Dashboard)

The same data, authenticated with your browser session (JWT). This is what the dashboard UI calls — if you are building a headless integration, prefer /v1/account/tier above.

Auth: Dashboard (JWT)

Limits may change — always read /api/tier for your real limits. Today every account gets the same limits, whatever plan you are on.

When you exceed a limit the API returns HTTP 429 with standard rate-limit headers:

Rate-limit headers (on 429)

X-RateLimit-Limit: 60          # your per-minute request cap
X-RateLimit-Remaining: 0       # requests left in the current window
X-RateLimit-Reset: 1718659245  # unix time when the window resets
Retry-After: 12                # seconds to wait before retrying

On HTTP 429 Too Many Requests, read the Retry-After header and wait that many seconds before retrying. Do not retry immediately.

429 response

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718659245

{
  "detail": "Rate limit exceeded. Retry after 12 seconds."
}

Separate from request limits, each account has a daily credit cap. When it is reached the API also returns 429 with a Retry-After header; the cap resets at 00:00 UTC.

Handling rate limits

  1. Watch for 429s

    Treat HTTP 429 as a signal to slow down, not an error to surface to users.

  2. Honor Retry-After

    Wait for the number of seconds in the Retry-After header before the next attempt.

  3. Back off exponentially

    For repeated 429s, increase the wait each time (for example 1s, 2s, 4s) with a capped maximum and a retry limit.

Retry with backoff

python

import time
import requests

def api_request(method, url, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        resp = requests.request(method, url, **kwargs)
        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", "5"))
            print(f"Rate limited; waiting {retry_after}s")
            time.sleep(retry_after)
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError("Max retries exceeded")

javascript

async function apiRequest(url, options = {}, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, options);
    if (res.status === 429) {
      const retryAfter = parseInt(res.headers.get("Retry-After") || "5", 10);
      console.log(`Rate limited; waiting ${retryAfter}s`);
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      continue;
    }
    if (!res.ok) throw new Error(`API error: ${res.status}`);
    return res.json();
  }
  throw new Error("Max retries exceeded");
}

FAQ

How do I find my actual rate limits instead of guessing?

Call GET /v1/account/tier with your API key — it returns your real requests_per_minute, requests_per_day, concurrent_limit, and max_credits_per_day for your account. Limits are tier-based, so don't hardcode numbers.

What happens when I exceed a rate limit?

The API returns HTTP 429 with X-RateLimit-* headers and a Retry-After header telling you how many seconds to wait. Read Retry-After and wait — don't retry immediately.

Is the daily credit cap the same thing as the rate limit?

No — they're separate. Request-rate limits govern how many calls you can make per minute/day; the daily credit cap governs total spend per day. Both return 429 when exceeded, and the credit cap resets at 00:00 UTC.

Honor Retry-After first, then back off exponentially on repeated 429s (e.g. 1s, 2s, 4s) with a capped maximum and a retry limit — see "Retry with backoff" above for working Python and JavaScript examples.

Should I cache my tier limits, or check them on every request?

Cache them. Call /v1/account/tier once at startup — tier limits rarely change mid-session.

Build with PicX

One API key and one credit balance across the REST API, MCP server, CLI and SDKs.