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
`unauthorized`	Missing or invalid API key	Check the `X-API-Key` header
`not_found`	The ad, advertiser or job does not exist	Check the id
`rate_limited`	Over your plan's requests per minute	Wait for `Retry-After` seconds
`quota_exceeded`	Monthly credits and packs used up	Buy a pack or upgrade; 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

Plan	Requests per minute
Free	10
Starter	60
Growth	120
Pro	300
Business	600

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.