What Do Ads Insights API Error Codes Mean?

When an Ads Insights call fails, the response carries an error code and a subcode. The code alone is too broad, because the same code covers different causes. This page explains six pairs from Meta’s Ads Insights error code list, updated 21 May 2026, as checked on 2 Oct 2026. Meta’s page also lists the rest, so use it when your pair is not here.

What do the common error pairs mean?

Code and subcode	Source	Meta’s summary	What Meta suggests
100, 1504018	Sync	Request timed out	Try a smaller date range, fetch less data, or use async jobs
4, 1504022 or 1504039	Async and sync	Too many API requests	Your app exceeded the allowed number of requests; wait before retrying
2, 1504041	Async and sync	Invalid breakdowns	No data exists for the requested metrics and breakdowns; try different ones
-3, 1504045	Async	Report too large	Check the documentation for guidance and try again
2, 1504043	Async and sync	Intermittent error	Retry at a later time
100, 3191001	Async and sync	Permission error	The Insights API denied the request because of insufficient permissions

Meta’s list also covers failed reports, other timeouts, invalid custom metrics and unexpected errors. Read the page for those.

What is the difference between sync and async errors?

A sync call is a GET request, and an async call is a POST job. Meta’s best-practices page says sync requests can return out-of-memory or timeout errors, and async requests can return timeout errors. An async request can take up to an hour to complete, including retry attempts.

Meta’s advice is to try sync calls first and use async calls when sync calls time out. It also says to use batch requests for multiple sync calls.

Why does a request time out?

Meta says timeouts and too many requests are the most common cause of Insights failures. There is no explicit limit for when a query will fail. When it times out, Meta says to break the query into smaller ones with filters such as a date range.

Meta also says unique metrics are time consuming to compute, so query them in a separate call from non-unique metrics.

What makes a report too large?

Meta describes data-per-call limits that stop a query from pulling more than the system can handle. There are two kinds: the number of rows in the response, and the number of data points needed to compute the total, such as a summary row. These limits apply to sync and async calls.

To stay under them, Meta says to limit the date range or the number of ad IDs, ask only for the metrics you need, and avoid account-level queries with high-cardinality breakdowns such as action_target_id or product_id.

What should you do when an Insights call fails?

1. Read the error code and subcode from the response.
2. Find the pair in the table on Meta’s error codes page.
3. Shorten the date range, reduce the ad IDs or request fewer metrics.
4. Switch a timed-out sync call to an async job.
5. Wait and slow your calls if the error is “too many API requests”.

For the limits behind that last error, see how Marketing API rate limits work.

FAQ

Why does one error code appear with several subcodes?

The subcode identifies the cause. In Meta’s table, code 100 appears with 1504018 for a timed-out sync request and with 3191001 for a permission error. Code 4 appears with both 1504022 and 1504039, and both mean too many API requests.

Does the error list cover async calls?

Meta’s page says error code information for async sources will be available with Marketing API v25.0 and later. Its Source column marks each pair as sync, async or both. Check which of your calls are async before you rely on a pair.

Is there a size at which an Insights query fails?

Meta says there is no explicit limit for when a query will fail. A query that times out should be split into smaller queries with filters like date range. For async requests, Meta says completing one can take up to an hour, retries included.