Docs

Errors and rate limits

AdLib error format, error codes, per-minute rate limits by plan, rate limit headers and how to retry.

Error format

Errors return a JSON body with a machine-readable code:

JSON
{
  "error": {
    "code": "not_found",
    "message": "ad meta:123 not found",
    "request_id": "c821fd4d-699b-4080-9776-841f4b57aad2",
    "billed": false
  }
}

Errors are never billed. Quote the request_id (also in the X-Request-Id header) when you contact us.

Codes

Code Meaning What to do
bad_request A parameter is missing or invalid; details says which Fix the request
invalid_cursor The cursor did not come from a next_cursor Pass next_cursor back unchanged
invalid_webhook_url The webhook URL is not a public http(s) address (localhost, private, link-local and internal hosts are refused) Use a URL reachable from the internet
interval_too_short interval_hours is below what your account allows (24 on the free credits, 6 once you have bought a pack) Raise interval_hours or buy a pack
watchlist_too_large The watchlists would watch more brands than your account allows (3 on the free credits, 250 after a pack) Remove brands or buy a pack
batch_too_large More items in a batch than your account allows (10 on the free credits, 100 after a pack) Split the batch
unauthorized Missing or invalid API key Check the X-API-Key header
account_blocked The account is blocked Contact us
history_limit The ad is older than your account's archive (12 months on the free credits) Buy a pack for the full archive
not_found The ad, advertiser, job or endpoint does not exist Check the id or the path
rate_limited Over your account's requests per minute (30 on the free credits, 300 after a pack) Wait for Retry-After seconds
quota_exceeded Free credits and packs used up Buy a pack; don't retry
upstream_error The platform's library failed or blocked the request Retry later; check status
internal_error Our side failed Retry; tell us if it persists

Rate limits

Account Requests per minute
On the free credits 30
After the first credit pack 300

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets). Over the limit the API answers 429 rate_limited with a Retry-After header.

Retries

Retry rate_limited, upstream_error and internal_error with backoff. Don't retry bad_request, unauthorized, not_found or quota_exceeded. Platforms sometimes change their libraries without notice; when one breaks, its calls fail fast, are not billed, and show up on the status page.