By Matija, the developer behind Build with Matija. I run a Next.js MCP server with about forty Google Ads tools that call the REST API directly. Tested with Next.js 16.3, TypeScript 5.9, Node 22 and the Google Ads API v26. Last updated 2026-10-25.
When Google sunsets a Google Ads API version, every request to it fails with requestError: UNSUPPORTED_VERSION, and your OAuth tokens keep working the whole time. A status check that only looks at stored tokens will report "connected" while every real call is broken. The fix has four parts: resolve the API version in one place with a minimum the code refuses to go below, make the status check call the API itself, turn Google's error body into a small set of named categories with a hint for each, and retry only the read-only calls. This guide shows each part as I wrote it after v22 was sunset on 7 October 2026 and my integration broke.
What broke and why the status check lied
My site runs an MCP server that Claude uses for keyword research and campaign work. The Google Ads client in it pinned the version with an environment variable and a fallback.
That fallback was fine when I wrote it. Google publishes a sunset date for every version and announced that v22 requests would start failing on 7 October 2026. After that date, every tool returned an error that looked like this one, buried in a raw JSON string.
text
Google Ads request failed: 400 Bad Request - {"error":{"code":400,"details":[{"errors":[{"errorCode":{"requestError":"UNSUPPORTED_VERSION"}, ...
The part that cost me time was the status tool. get_google_ads_status checked whether a Google Ads token was stored for the user and returned { "connected": true }. The agent read that, assumed the account was fine, and kept retrying tools that could never succeed. OAuth answers one question (do we hold a valid token) and the API version answers another (will Google accept this request shape at all). A health check has to cover both.
Moving to a new version was only part of the work. Between v22 and v26 the request shapes changed too, so the version bump had to come with code changes.
Step 1: Resolve the version in one place with a floor
The first change moves the version logic into its own transport module. The constant describes the version the queries in the codebase are written for, and anything older pinned in the environment is ignored with a warning.
typescript
= ;
(): | {
match = .(value);
match ? (match[]) : ;
}
(): {
raw = configured?.().(, );
(!raw) ;
major = (raw);
minimum = ()!;
(major === || major < minimum) {
.(
,
);
;
}
;
}
= ();
= ;
The reason for the floor is that an old pin in a hosting dashboard outlives the code that needed it. My production environment still had GOOGLE_ADS_API_VERSION=v22 set from months earlier. If the code had simply trusted the variable, the deploy with the new queries would have kept calling v22 and failed in exactly the same way. With a floor, the code decides which version it can talk to and the environment can only move it forward, for example to try v27 before changing the default.
The parser also cleans up the things people actually type into environment variables: surrounding quotes, v26.0, or a bare 27. A value like latest is not a version, so it falls back to the default.
Step 2: Update the queries that changed between versions
The version number is the easy part. Two request shapes in my code no longer existed in v26.
The first was the campaign date fields. From v23, GAQL uses campaign.start_date_time and campaign.end_date_time in place of campaign.start_date and campaign.end_date, and the response rows carry startDateTime and endDateTime in the customer's time zone.
The second was paging. My GoogleAdsService.Search calls sent an explicit pageSize, and on v26 that came back as requestError: PAGE_SIZE_NOT_SUPPORTED. The request now sends only the query and the pageToken.
Google publishes a diff tool for each version pair, and going through the resources you query (campaign, ad group, keyword plan ideas) before changing the default saves you from finding these one tool at a time in production.
The third change was about credentials. During the same period Google moved API access from the developer token to the Google Cloud project that owns the OAuth client, with access levels set per project. My client used to throw when GOOGLE_ADS_DEVELOPER_TOKEN was missing. Now the header is sent only when the variable exists.
If you set up access with my Google Ads MCP setup guide, the developer token step there reflects how access worked when it was written. Check your Cloud project's access level in the API Center if production accounts are refused.
Step 3: Turn Google's error body into categories an agent can act on
A raw JSON error string is hard for a person to read and worse for an agent. I wanted every failure to answer three questions: which service and method failed, which kind of failure it was, and what to do next. The parser reads Google's GoogleAdsFailure body, collects every errorCode, and maps them to one of ten categories.
The order of the checks matters. A sunset version and a Cloud project without production access both come back as HTTP 400 or 403, so the specific error codes are checked before the HTTP status. Otherwise a version problem would be filed under "invalid request" and an access problem under "permission denied", and both would send you looking in the wrong place.
Each category carries a one-line hint, and the error object keeps the details as structured data next to a readable summary.
The hints are written for the reader most likely to see them first, which in my case is an AI agent calling an MCP tool. "Regenerating tokens will not help" is there because the natural reaction to any Google auth-looking error is to reconnect OAuth, and for a Cloud project access problem that loop never ends. The request id is kept because it is the one thing Google support asks for. Messages are passed through a sanitizer that redacts Bearer tokens and ya29. access tokens and caps the length, since these details end up in logs and in tool results.
To get the details out to the agent, the shared MCP error helper now includes them when an error carries a details object.
Every tool in the server uses this helper, so any upstream client that attaches details gets the same structured output without touching the tools. If you are building your own server, my guide to building an MCP server in Next.js shows where a helper like this sits.
Step 4: Retry reads, never mutations
With categories in place, retries become a decision per category. Only quota and transient errors are marked retryable, plus network failures from fetch. Everything else, a sunset version included, fails on the first attempt, because repeating the same request against a sunset version only adds latency.
The request function takes a retry flag, and only read-only calls set it: listAccessibleCustomers, googleAds:search, and the three Keyword Planner methods. Mutations such as creating a campaign or updating an ad never retry. A 500 on a mutate call does not tell you whether Google applied the change, and a blind retry can create a second campaign or a second ad. For writes, the safer behaviour is to report the failure with its request id and let the caller check state before trying again.
Step 5: Make the status check call the API
The last change is the one that would have saved me the most time. get_google_ads_status still reports whether tokens are stored, and when they are, it makes one cheap real call and reports the result under a separate api key.
listAccessibleCustomers is a good probe because it needs no customer id and no manager header, so it fails only for reasons that affect every other call too: the version, the token, or the Cloud project's access. When v22 was sunset, this tool would have returned connected: true and api.available: false with category unsupported_version and the hint to update the version, which is the whole diagnosis in one response.
The tool description spells out what each field means. Agents read tool descriptions, and a field called connected invites the assumption that everything works.
Step 6: Test the request builders without the CMS
The Google Ads client lives inside a Payload CMS app, and the token lookup imports Payload. Loading that in a unit test means starting the CMS. To avoid it, the client goes through a small transport object that tests can replace.
The dynamic import means the Payload-backed module loads only when a real token is needed. The tests swap both functions, record every request and assert on URLs, headers and bodies.
The suite has 23 tests and runs with Node's built-in runner through tsx in under a second: node --import tsx --test src/lib/google/google-ads.test.ts. It covers version resolution, headers, the date field change, the missing pageSize, every error category, and the rule that mutations never retry. The next sunset will need a new default and a pass through the diff tool, and the tests will show which request shapes the change touched.
FAQ
How do I know when my Google Ads API version will be sunset?
Google lists the sunset date of every version on its sunset dates page and posts reminders on the Google Ads developer blog a few weeks before. Put the date of the version you use in your own calendar, because nothing in your code will warn you before requests start failing.
Why not always read the version from an environment variable?
You can, as long as the code sets a minimum. The queries in your codebase are written for one version's field names, so an older version pinned in the environment will fail even if it is still supported. A floor in code lets the environment move forward for testing without letting it move back.
Is it safe to retry Google Ads mutate calls on a 500?
I don't retry them. A server error on a mutate call does not tell you whether the change was applied, and a retry can create duplicates. Read the current state with a search query first, then decide whether to send the change again.
My tokens are valid but every call returns CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION. What now?
That error is about the Google Cloud project that owns your OAuth client. It needs Basic or Standard access to work with production accounts. Reconnecting OAuth or creating a new token will not change it.
Does this apply to the official Google Ads client libraries?
The client libraries pin a version for you and drop old ones in new releases, so the fix there is upgrading the library. The status check, the error categories and the read-only retry rule apply either way.
Conclusion
A Google Ads API sunset breaks every call on a fixed date while OAuth keeps reporting that the account is connected. In my MCP server I fixed that with a version resolved in one module with a floor, the GAQL and paging changes the new version needed, error categories with hints written for agents, retries limited to read-only calls, and a status tool that calls the API before it says the integration works. You can apply the same pattern to any versioned API your app depends on: decide the version in code, check health with a real request, and classify errors so the next failure explains itself.
Let me know in the comments if you have questions, and subscribe for more practical development guides.