Errors

HTTP status codes and how to handle them.

The API returns standard HTTP status codes. 2xx is success, 4xx is a request error, 5xx is a server error. Error responses usually include a JSON body describing the problem.

Status codes

Code	Meaning	What to do
`200 OK`	Success	—
`400 Bad Request`	Invalid parameters (missing `from`/`to`/`metrics`, bad date, range over 90 days, invalid dimension/metric combination)	Fix the request parameters
`401 Unauthorized`	Key missing, invalid or expired	Check the `Authorization` header
`403 Forbidden`	Key valid but no access to the resource	Use a `campaign_id`/`ad_id` you own
`404 Not Found`	Path or resource not found	Check the URL
`429 Too Many Requests`	Rate limit exceeded	Retry with backoff
`5xx`	Transient server/edge error	Retry after a short wait

Common mistakes

400 — date range too wide: from–to must be at most 90 days.
400 — keyword + date: keyword is totals-only and can't be combined with date.
400 — keyword + conversions: keyword supports only views/spending/clicks.
401 — missing Bearer: the header must be Authorization: Bearer <API_KEY>.

Recommendations

Do not retry 4xx errors — the request is malformed, fix the parameters.
For 429 and 5xx, retry with exponential backoff.
Log the message in the response body; it makes debugging easier.

Rate Limits & Caching

Edge caching behavior, rate limits and handling 429.

Unified stats report GET

One endpoint, one row shape: `{ dimensions, metrics }`. - metrics: views, spending, clicks (valid/bot-filtered), conversions. - dimensions: omit for a grand total; `date` buckets by granularity; one entity dimension (campaign|ad|keyword) optionally combined with date. - keyword is totals-only and supports views/spending/clicks (not conversions). - `date` is unix epoch seconds (UTC, bucket start). Community data is out of scope.

On this page

Status codes Common mistakes Recommendations