Errors

A v3 tool can fail while the MCP transport succeeds. Always inspect the tool result: a failure has isError: true and a structured body. Read structuredContent.code and the fields beside it, never the rendered text.

The error shape

{
  "isError": true,
  "structuredContent": {
    "code": "REVISION_CONFLICT",
    "message": "Campaign cmp_01JB… changed since revision 4.",
    "recovery": "fix_input",
    "field": "expectedRevision",
    "suggestion": "Read the campaign again and retry with its current revision."
  }
}

Field	Meaning
`code`	Stable, machine-readable reason. Branch on this.
`message`	A sentence for people. It can change; do not parse it.
`recovery`	What to do next: `retry`, `fix_input`, `ask_user`, `contact_support` or `none`.
`field`	The input field at fault, when there is one.
`suggestion`	A concrete next step, when the server has one.

Two results that are not errors

result

{ "status": "needs_input", "question": "…", "missingFields": ["budget.currency"] }. A required fact is missing. Ask the person the question, then call again with the answer. Never invent a value to get past it.

result

{ "status": "pending_confirmation", "confirmationUid": "cnf_…", "summary": "…", "expiresAt": "…",     "writeExecuted": false }

. The write is paused for a person’s approval. Show the summary; after they approve, call the same tool again with confirm: true and the confirmationUid (for a campaign launch, confirmLaunch: true). Confirmations expire after 15 minutes.

Common codes

Code	What happened	What to do
`VALIDATION_ERROR`, `BAD_REQUEST`	The input did not match the schema.	Fix `field` and call again. Check the Tool Catalog.
`CURRENCY_MISMATCH`	The budget currency differs from the advertiser’s.	Use the advertiser’s primary currency.
`UNAUTHORIZED`	No valid credential.	Re-run OAuth or check the API key.
`FORBIDDEN`, `ACCESS_DENIED`	The account or role cannot do this.	Call `get_status`; switch accounts or ask an admin.
`TOS_ACCEPTANCE_REQUIRED`	The organization has not accepted the current terms.	Ask an admin to accept them in Plan & billing.
`NOT_FOUND`	No such object in the active account.	Check the id and the active account.
`REVISION_CONFLICT`	Someone changed the object since you read it.	Read it again and retry with the new `expectedRevision`.
`CONFLICT`	The same idempotency key was used with a different body, or the object is in the wrong state.	Use a new key for a new attempt; re-read state.
`BUYER_SETUP_REQUIRED`	Buyer setup is incomplete for this seller or advertiser.	Follow the next action from `get_status`.
`INSUFFICIENT_MEDIA_BUDGET`	Allocations exceed the campaign budget.	Lower allocations or raise the budget.
`CAPABILITY_NOT_SUPPORTED`	The seller or account cannot do this.	Choose another seller or approach.
`RATE_LIMITED`	Too many requests.	Wait for `Retry-After`, then retry.
`SERVICE_UNAVAILABLE`, `INTERNAL_ERROR`	A temporary platform problem.	Retry with the same idempotency key and backoff.

NOT_FOUND deliberately hides whether an object exists in some other account. Do not read it as evidence about accounts you cannot see.

Partial results

Some tools talk to many sellers at once, so success is not all-or-nothing.

Proposal requests report each seller separately: quoted, products or failed, with a summary such as “Asked 9 sellers · 6 responded · 2 pending · 1 failed”. Keep the good answers; one failed seller does not spoil the execution.
Campaign launch returns mediaBuysExecuted and one entry in errors per failed media buy, each with recovery (transient, correctable or terminal) and retrySafe. Launching again resubmits only the failed draft buys.

Retrying safely

If a call timed out or the connection dropped, read first: the write may have happened.
Retry a write with the same idempotencyKey only if it is the same logical attempt. Change the key when you change the request.
After a REVISION_CONFLICT, re-read, re-decide, then write with the new revision. Do not blindly bump the number.

v3

Concepts

Agents

Skills

Buyer API reference

Storefront API reference

v3 API reference

The error shape

Two results that are not errors

Common codes

Partial results

Retrying safely

​The error shape

​Two results that are not errors

​Common codes

​Partial results

​Retrying safely

The error shape

Two results that are not errors

Common codes

Partial results

Retrying safely