AdnovaDocs
Concepts

Rate limits and versioning

How the Adnova APIs are rate-limited and how we version breaking changes.

Rate limits

Manage API (/manage/v1) and Analytics API (/analytics/v1)

Both surfaces use the same policy in each service:

  • 100 requests per 60 seconds per authenticated user. The count applies to all routes on that API (not per endpoint).

  • There is no separate burst pool beyond that per-user quota in the active window on each service.

  • Response headers use the common RateLimit*-style fields (IETF rate-limit header draft) so you can read remaining quota and when the window resets. Check those headers on the response; 2xx JSON bodies do not repeat that information.

  • When exceeded, the API returns 429 with a JSON body like below. For this case, rely on the error payload, and any RateLimit* headers on the response to see when you can try again.

    {
      "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Rate limit exceeded"
      }
    }

Analytics refresh (POST /analytics/v1/refresh)

In addition to the global limit above, refresh uses a separate cooldown so expensive platform work cannot be spammed:

  • One successful refresh per (platform, adAccountId, datePreset) every 15 minutes.
  • If you hit this limit, the response is 429 with a Retry-After header (seconds) and a JSON body that includes retryAfterSeconds.

Ad Launcher API (/ad-launcher/v1)

Ad Launcher splits read and write into two independent buckets:

  • General — ~100 req / 60 s per user. Applies to lookups, the creative-upload handshake, and GET /launches/{batchId}.
  • Launch (write) — POST /launches only. Much stricter; quota is configured per org in adnova_ad_launcher.

Because the buckets use distinct Redis key prefixes, spamming POST /launches does not eat into your read budget. See Ad Launcher rate limits for details.

Versioning strategy

The API is versioned in the URL path — e.g. /manage/v1/..., /analytics/v1/..., /ad-launcher/v1/.... A new major version only ships when we need to make a breaking change.