Rate limits & errors

Overview

Plan capacity is fixed for v1: the $50 USD/month subscription (first month $40 with the 20% upgrade discount) unlocks the full catalog, up to 20 named keys, unlimited serial original downloads, and a shared 30 authenticated requests per minute ceiling. The free trial runs at 2 requests/minute with a lifetime budget of 2,000 image requests (responses carry X-Trial-Requests-Remaining). Creating more keys does not multiply the rate limit or the concurrent-download lease.

Rate limits

The limit is 30 authenticated API requests per minute per account. Catalog endpoints that require a Bearer key (search, detail, batch, tags, stats, minting download tokens, and similar) consume this budget. Binary original transfer via a signed download_url does not consume an extra catalog request, but it is governed by the one-at-a-time concurrency lease described on Downloads.

• Limit scope: per account, not per key and not per IP alone.
• Extra keys share the same 30/minute ceiling—they do not stack.
• When the budget is exhausted, the API returns HTTP 429, a Retry-After delay, and rate_limit_exceeded.
• Design for burst-friendly patterns: batch metadata, cache hot searches, and serialize export pipelines.

Rate-limit response headers

Successful and many error responses include the current budget state. Use them to throttle proactively instead of waiting for 429.

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 24
X-RateLimit-Reset: 1784498400

Reduce request usage with batch

POST https://epochalstock.com/api/v1/images/batch accepts 1–100 unique image IDs and counts as one API request. Prefer batch when a design workflow already knows many IDs instead of issuing one GET /images/{id} per asset.

Details and examples: Image detail & batch.

Error JSON shape

Error responses use a consistent envelope. Branch on error.code for machine-readable handling; show or log message for humans; always retain request_id.

{
  "error": {
    "code": "invalid_parameter",
    "message": "q must not exceed 200 characters.",
    "details": { "parameter": "q" },
    "request_id": "req_..."
  }
}

Successful JSON uses data plus meta.request_id. Do not assume error bodies appear on every non-JSON response (for example some binary download failures).

Error reference

Full catalog of documented HTTP statuses and codes for the Developer Image API v1.

Retry strategy

Retries are safe only for a small set of statuses. Blindly retrying validation or auth failures will not help and can worsen rate-limit pressure.

• Set connect and read timeouts on every HTTP client.
• Backoff formula example: min(cap, base * 2^attempt) + random_jitter.
• Honor Retry-After as a minimum sleep when the server provides it.
• Idempotent GETs are safer to retry than duplicate side effects; still respect rate limits.
• Never retry with a different leaked key strategy—fix auth configuration instead.

Backoff code examples

Minimal patterns for retrying transient failures (429, 502, 503) with exponential backoff and jitter. Load secrets from the environment only.

async function fetchWithBackoff(url, options = {}, maxAttempts = 5) {
  let attempt = 0;
  for (;;) {
    const res = await fetch(url, options);
    if (res.ok) return res;

    const retryable = [429, 502, 503].includes(res.status);
    if (!retryable || attempt >= maxAttempts - 1) {
      const body = await res.text();
      throw new Error(`HTTP ${res.status} id=${res.headers.get("x-request-id")} ${body}`);
    }

    const retryAfter = Number(res.headers.get("retry-after"));
    const base = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000
      : Math.min(30_000, 500 * 2 ** attempt);
    const jitter = Math.floor(Math.random() * 250);
    await new Promise((r) => setTimeout(r, base + jitter));
    attempt += 1;
  }
}

// Example: catalog search
const res = await fetchWithBackoff(
  "https://epochalstock.com/api/v1/images?limit=30",
  {
    headers: {
      Authorization: `Bearer ${process.env.EPOCHAL_API_KEY}`,
      Accept: "application/json",
    },
  }
);
const json = await res.json();

import os
import random
import time
import requests

RETRYABLE = {429, 502, 503}

def fetch_with_backoff(method, url, *, max_attempts=5, **kwargs):
    attempt = 0
    while True:
        r = requests.request(method, url, timeout=20, **kwargs)
        if r.ok:
            return r
        if r.status_code not in RETRYABLE or attempt >= max_attempts - 1:
            rid = r.headers.get("X-Request-ID")
            raise RuntimeError(f"HTTP {r.status_code} request_id={rid} body={r.text}")

        retry_after = r.headers.get("Retry-After")
        if retry_after and retry_after.isdigit():
            delay = float(retry_after)
        else:
            delay = min(30.0, 0.5 * (2 ** attempt))
        delay += random.uniform(0, 0.25)
        time.sleep(delay)
        attempt += 1

r = fetch_with_backoff(
    "GET",
    "https://epochalstock.com/api/v1/images",
    params={"limit": 30},
    headers={
        "Authorization": f"Bearer {os.environ['EPOCHAL_API_KEY']}",
        "Accept": "application/json",
    },
)
print(r.headers.get("X-RateLimit-Remaining"), r.json())

function fetch_with_backoff(string $url, array $headers, int $maxAttempts = 5): string
{
    $attempt = 0;
    while (true) {
        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => $headers,
            CURLOPT_TIMEOUT => 20,
            CURLOPT_HEADER => true,
        ]);
        $raw = curl_exec($ch);
        $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $headerSize = (int) curl_getinfo($ch, CURLINFO_HEADER_SIZE);
        $headerBlob = substr((string) $raw, 0, $headerSize);
        $body = substr((string) $raw, $headerSize);

        if ($status >= 200 && $status < 300) {
            return $body;
        }

        $retryable = in_array($status, [429, 502, 503], true);
        if (!$retryable || $attempt >= $maxAttempts - 1) {
            throw new RuntimeException("HTTP {$status}: {$body}");
        }

        $retryAfter = 0.0;
        if (preg_match('/^Retry-After:\s*(\d+)/mi', $headerBlob, $m)) {
            $retryAfter = (float) $m[1];
        }
        $base = $retryAfter > 0 ? $retryAfter : min(30.0, 0.5 * (2 ** $attempt));
        $jitter = mt_rand(0, 250) / 1000;
        usleep((int) (($base + $jitter) * 1_000_000));
        $attempt++;
    }
}

$headers = [
    'Authorization: Bearer ' . getenv('EPOCHAL_API_KEY'),
    'Accept: application/json',
];
$json = fetch_with_backoff(
    'https://epochalstock.com/api/v1/images?limit=30',
    $headers
);

Why X-Request-ID matters

Every API response includes X-Request-ID. Error JSON usually mirrors it as error.request_id; successful bodies often expose meta.request_id. This is the primary correlation token for support, incident review, and multi-service logs.

Next steps