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:
{
"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.