Errors

The v2 REST API uses a single, predictable error envelope across every endpoint. Whatever the failure — a missing auth token, a Zod validation problem, a 404, a downstream rate limit — the body shape is the same. Build your error-handling once and reuse it everywhere.

This page covers v2 REST endpoints. MCP tool errors follow the ADCP error spec and are returned in structuredContent rather than HTTP status codes.

Error envelope

Every non-success response has data: null and a populated error object:

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "field": "name",
    "details": {
      "issues": [
        { "path": "name", "message": "Required" }
      ]
    }
  }
}

Field	Type	Always present	Description
`code`	`string`	yes	Machine-readable error code (see table below)
`message`	`string`	yes	Human-readable message safe to surface to end users
`field`	`string`	no	Field path for validation errors (e.g. `start_date`, `targeting.geos`)
`details`	`object`	no	Structured payload — Zod issues, conflict resource ids, retry hints, etc

Successful responses have the inverse shape: { "data": <result>, "error": null }. List endpoints add a meta block (see Pagination).

Throughout the Buyer and Storefront task references, the ## Response examples show the data payload only — the inner result. On the wire it is always wrapped in the envelope above: { "data": <payload>, "error": null }, plus a meta block on list endpoints. Read the result from response.data.

HTTP status codes

Status	Meaning	Typical `code` values
`400`	Malformed request	`BAD_REQUEST`, `VALIDATION_ERROR`, `CURRENCY_MISMATCH`
`401`	Missing or invalid auth	`UNAUTHORIZED`
`403`	Authenticated but not allowed	`FORBIDDEN`, `ACCESS_DENIED`, `ALPHA_OPT_IN_REQUIRED`, `TOS_ACCEPTANCE_REQUIRED`
`404`	Resource doesn’t exist or isn’t visible to you	`NOT_FOUND`
`409`	Conflicting or incomplete account state	`CONFLICT`, `BUYER_SETUP_REQUIRED`, `PRICING_NOT_CONFIGURED`, `INSUFFICIENT_MEDIA_BUDGET`
`422`	Semantically invalid (rare — most things use 400)	`VALIDATION_ERROR`, `CAPABILITY_NOT_SUPPORTED`, `SPEND_DENOMINATION_UNRESOLVED`
`429`	Rate limit hit	`RATE_LIMITED` (see Rate Limits)
`500`	Unhandled server error	`INTERNAL_ERROR`
`501`	Endpoint exists but not yet implemented	`NOT_IMPLEMENTED`
`503`	Upstream / dependency unavailable	`SERVICE_UNAVAILABLE`, `SIGNUP_EXPERIENCE_STATE_UNAVAILABLE`

Common error codes

Code	When you’ll see it
`VALIDATION_ERROR`	Zod schema rejected the request body, query, or params
`BAD_REQUEST`	Generic 400 — usually a malformed param that didn’t reach Zod
`UNAUTHORIZED`	No bearer token, expired token, or unknown API key
`FORBIDDEN`	Auth succeeded but you lack the role/permission
`ACCESS_DENIED`	Resource exists but is owned by a different account/advertiser
`NOT_FOUND`	Resource ID doesn’t exist (or is hidden from your scope)
`CONFLICT`	Duplicate resource, illegal state transition, or invariant violated
`BUYER_SETUP_REQUIRED`	Buyer operator identity is incomplete. Open Buyer Setup, complete step 1, then retry; see the structured contract below. V3 `get` of a wholesale product also returns it, with `details.reason` `account_needs_attention` or `account_pending`, when the media partner has not finished setting up your account for that advertiser; open Media Partners.
`RATE_LIMITED`	Too many requests — back off and retry after `Retry-After`
`INTERNAL_ERROR`	Unhandled exception — safe to retry once
`SERVICE_UNAVAILABLE`	A dependency (downstream agent, billing, contract verification, signal provider, the check that confirms your access to an advertiser) is temporarily down. Retry the request; unlike `TOS_ACCEPTANCE_REQUIRED`, this does not mean your organization needs to accept terms, and unlike `ACCESS_DENIED`, nothing refused the request.
`SIGNUP_EXPERIENCE_STATE_UNAVAILABLE`	A declared enrolled dark signup routing intent could not be stored or used as server-authoritative state. Returned only by legacy `GET /auth/url`, `GET /auth/sso/url`, `POST /auth/token`, and `POST /auth/sso/callback` as the flat HTTP 503 body `{ "error": "SIGNUP_EXPERIENCE_STATE_UNAVAILABLE", "message": "...", "retryable": true }`, not the v2 error envelope. Restart sign-in for a new state. It does not expose the selected value or authorize any signup/provisioning action.

Domain-specific codes you may encounter on campaign, currency, and reporting endpoints:

Code	Meaning
`PRICING_NOT_CONFIGURED`	Advertiser has no pricing rule for the selected sales agent. Also returned when a campaign budget change involves media buys whose fee terms cannot be determined — `details.unpricedBuyIds` names them; resolve pricing for those buys first
`CURRENCY_MISMATCH`	Budget currency doesn’t match the agent or storefront currency
`INSUFFICIENT_MEDIA_BUDGET`	The campaign’s `budget.total` can’t cover its media buys — e.g. lowering the total below what live buys already allocate. The error names the requested total and the committed allocation
`ROUTED_AGENT_REQUIRES_OPERATOR_AUTH`	Deprecated compatibility code for older clients. If received, operator credentials are missing; do not infer a storefront type from the name.
`SPEND_DENOMINATION_UNRESOLVED`	Reporting was asked for money it cannot denominate: one or more media buys in scope have delivery spend with no resolvable currency, so no figure would be correct. Returned as HTTP 422 and classified `terminal` — retrying reproduces it, because the cause is data that is wrong at rest (a source reporting a currency it is not paid in, a buy missing its cross-currency booking evidence, or currencies mixed within the period). The affected buys are named in `message` and in `details.mediaBuyIds`, with `details.unresolvedCount`. Report those ids to support; to keep reporting meanwhile, scope the request to exclude them. Distinct from `FX_RATE_UNAVAILABLE`, which is a rate-feed outage and is retryable. See Cross-currency
`FX_RATE_UNAVAILABLE`	No exchange rate could be resolved for a currency pair — the rate feed is down with nothing recent to carry forward. Returned as HTTP 503 and classified `transient`; retry shortly
`FX_QUOTE_EXPIRED`	The FX quote behind a selected pricing option is from an earlier UTC day. Rates are fixed per UTC day; re-run discovery for a current quote, then resubmit
`ALPHA_OPT_IN_REQUIRED`	Feature is in alpha — opt in via support before using
`TOS_ACCEPTANCE_REQUIRED`	Account must accept the latest terms of service before mutating
`CAPABILITY_NOT_SUPPORTED`	Campaign update targets a media buy whose downstream sales agent does not declare support for the requested operation. `details.unsupported[]` lists each `{ mediaBuyId, salesAgentId, field, reason }`. The update is rejected upfront with no state changes; fix by removing the unsupported `mediaBuys[]` entries or waiting for the agent to declare support.
`VERSION_UNSUPPORTED`	Either an AdCP source rejected the negotiated version, or `sync_accounts` contains `3.2` identity fields that the storefront cannot safely represent. For negotiation, this is correct only for a cross-major mismatch; a same-major release gap must be downshifted. For the request-shape gate, `details.reason` is `adcp_3_2_account_identity_not_supported`, `field` identifies the first incompatible value, and `details.unsupported_fields` lists all of them. See AdCP versioning & negotiation.
`MANAGED_ACCOUNT_LINKAGE_REQUIRED`	A `sync_creatives` call against a MANAGED storefront couldn’t serve its creatives because neither the calling buyer principal nor its buyer company has an active linked account for the request’s brand and operator on that storefront (grant not present, or in any non-`active` status). A request that names only the brand and operator uses the company’s active account automatically, so this error does not mean the request needs an `account_id`. The error appears as an `errors[]` entry on the per-creative `sync_creatives` result (`action: 'failed'`) — one entry per creative, all with the same code. The `message` carries a copy-pasteable `sync_accounts` request: `Run sync_accounts with {"accounts":[{"brand":{"domain":"…"},"operator":"…","billing":"agent","sandbox":?}]} on this storefront to request an account, then wait for the seller's approval.` The `sandbox` field is included only when the buy is sandbox-scoped. When the storefront forwards to the seller’s own sales agent and no account is on file for the buyer, the platform first requests the account from that seller with `sync_accounts` and continues with the account it returns; there, this error means the seller declined the account or is holding it for approval. Recovery depends on the grant state — check via `list_accounts` first, then act on the returned status: no grant → send the payload; the account enters `pending_approval` and retry after the seller approves. `pending_approval` → wait for the seller’s disposition; resubmitting `sync_accounts` returns `unchanged` and does not accelerate approval. `active` but you don’t have the `account_id` → retrieve it via `list_accounts` and include `account.account_id` on your next `sync_creatives`. `payment_required` → resolve the outstanding balance with the seller; per the AdCP spec the status transitions back to `active` after billing clears. `suspended` → contact the seller for reactivation; per the AdCP spec `suspended → active` is a seller-driven transition. `rejected` / `closed` → terminal per the AdCP Account Status Lifecycle; the grant cannot be re-approved and the buyer cannot resubmit under the same natural key without out-of-band re-onboarding with the seller.
`destination_profile_not_certified`	A managed ad-server route has no authenticated evidence for this video ingress yet. The creative fails before provider mutation. Do not retry the same route; use a certified destination or wait for certification.
`destination_rendition_required`	The hosted source could satisfy the destination after a managed rendition. Until managed rendition jobs are available, provide a file that already matches the destination profile.
`destination_profile_rejected`	The creative does not satisfy the managed destination profile. The per-creative message lists the failed constraints; correct or replace the source before retrying. A `missing:<field>` reason means required evidence is absent rather than wrong, such as the metadata of a hosted file that could not be inspected. A VAST tag URL saved without a version does not end here: Apostra reads the tag’s version when it sends (see `destination_vast_version_unavailable`). See video creatives.
`destination_vast_version_unavailable`	The creative is a VAST tag URL with no recorded `vast_version`, and Apostra could not read the version from the tag when it tried to send it (the tag did not answer in time, was unreachable, or returned no version). The fault is on our side and usually needs no change from you: the creative is not sent on this attempt, `sync_reason` is `destination_profile_refused` and `must_act` is `apostra`, and it is read again on the next sync. To stop depending on that read, set `vast_version` on the VAST asset. See video creatives.
`destination_destructive_sync_blocked`	A mixed `delete_missing` sync included both admitted and destination-rejected creatives. Nothing was forwarded because filtering the request could archive the rejected creatives. Correct the rejected creatives or retry without `delete_missing`.

Buyer identity and storefront account errors

Buyer operations that need a seller-side account fail closed when the buyer has no confirmed operator identity. REST returns HTTP 409 with BUYER_SETUP_REQUIRED; for a missing identity, branch on this exact structured payload:

{
  "data": null,
  "error": {
    "code": "BUYER_SETUP_REQUIRED",
    "message": "Complete Buyer Setup step 1 by confirming your buyer operator identity before continuing.",
    "details": {
      "reason": "missing_operator_identity",
      "readinessCheck": "operator_identity",
      "setupStep": 1,
      "setupPage": "buyer_setup"
    }
  }
}

Apostra never falls back to interchange.io as a buyer operator. Doing so would collapse unrelated buyers into one seller-side natural-key account. Complete Buyer Setup and retry instead. Historical media buys are not rewritten: status, creative re-sync, update, cancellation, and delivery keep using the seller account persisted on the buy. A legacy buyer profile that explicitly contains the platform domain returns the same BUYER_SETUP_REQUIRED code with details.reason: "platform_operator_not_allowed". This is observable on the same buyer surfaces as missing_operator_identity; replace the platform domain in Buyer Setup rather than retrying it. The Storefront MCP surface uses the ADCP error envelope rather than the REST envelope above. When a request supplies an opaque account_id that is not authorized for the authenticated buyer on that storefront, it returns:

{
  "code": "ACCOUNT_NOT_FOUND",
  "message": "The supplied account is not available to this authenticated buyer for this Seller.",
  "recovery": "correctable",
  "details": {
    "reason": "account_not_authorized_for_buyer"
  }
}

Do not interpret this as account_context_not_found, and do not retry with an account ID discovered by another buyer. Use list_accounts as the current buyer or complete the seller’s account-linking flow. An account that sends account_id together with brand or operator never reaches that check. It fails request validation with VALIDATION_ERROR, field: "account", and details.issues[] entries for /account (the additionalProperties and oneOf rules). Send either { "account_id": … } or { "brand": …, "operator": … }. On a seller in complete-key mode, see Address your approved account from a direct AdCP 3.0 or 3.1 agent for the full set of refusals. When you launch a campaign on an Apostra seller whose inventory runs on Apostra’s managed sales agent, the seller needs an account for the advertiser. That account is created when the advertiser is activated for the seller, so a launch that runs before activation finishes fails that buy with ACCOUNT_SETUP_REQUIRED (recovery: "correctable") before anything reaches the seller. The buy’s safeMessage and details.setup_steps name the step the advertiser’s activation still needs:

Markets and channels missing: activation cannot create the account until the advertiser has markets and channels. Set brandCountries and channels with save_advertiser.
Not enabled for the seller: turn the advertiser on for the seller with save_connection({ sellerId, advertiserActivation: { advertiserId, decision: "ENABLED" } }).
Still being set up, or waiting for the seller’s approval: wait, then retry.
Another required action, such as payment: complete it. details.setup_url links to it when one exists.

In every case, retry the launch once get({ kind: "seller", id }) shows the advertiser’s activation state as active. The buy is recorded as failed with the same explanation, owned by the buyer (invalid_request).

Buyer-actionable errors on `create_media_buy`, `update_media_buy`, `sync_creatives`

Buy-flow errors carry an optional buyer_reason: { code, message } sub-object on the ADCP error envelope (AdCP 3.2 core/error.json). It classifies the failure in a way the buyer can act on — creative-validation issues, budget/product/ permission problems — with a message that is safe to render directly (no vendor identifiers, no internal IDs, no stack traces). When buyer_reason is present, the envelope’s recovery (transient | correctable | terminal) is set alongside per spec and MUST agree with the buyer_reason’s classification. code uses the AdCP enums/error-code.json vocabulary (BUDGET_TOO_LOW, PRODUCT_NOT_FOUND, PRODUCT_UNAVAILABLE, PERMISSION_DENIED, ACCOUNT_SETUP_REQUIRED) or an X_{VENDOR}_{CODE} extension (Apostra extensions: X_SCOPE3_CREATIVE_SIZE_MISMATCH, X_SCOPE3_CREATIVE_MISSING_CLICK_URL, X_SCOPE3_CREATIVE_VALIDATION_FAILED_GENERIC). Receivers MUST preserve unknown codes for forward compatibility — a newer AdCP standard code or a seller-defined extension is passed through end-to-end.

{
  "code": "INVALID_REQUEST",
  "message": "The creative dimensions (300x250) don't match any accepted size on the selected packages (accepted: 640x480). Update the creative dimensions or select packages that accept 300x250.",
  "recovery": "correctable",
  "buyer_reason": {
    "code": "X_SCOPE3_CREATIVE_SIZE_MISMATCH",
    "message": "The creative dimensions (300x250) don't match any accepted size on the selected packages (accepted: 640x480). Update the creative dimensions or select packages that accept 300x250."
  },
  "details": {
    "reason": "all_sources_failed",
    "per_source": [
      {
        "source_id": "agent_1",
        "status": "failed",
        "error": "…",
        "buyer_reason": {
          "code": "X_SCOPE3_CREATIVE_SIZE_MISMATCH",
          "message": "…"
        },
        "recovery": "correctable"
      }
    ]
  }
}

The same buyer_reason may also appear on each entry of details.per_source so a per-leg diagnosis is available when a fan-out mixed causes; each entry carries its own recovery peer. On sync_creatives, buyer_reason + recovery appear on each failed creative row’s errors[] entry when the source classified the batch failure. Prefer reading the structured buyer_reason.code for programmatic routing (retry, mutate-and-resubmit, escalate) and use buyer_reason.message for what to show a human. For managed ad-server inventory, local targeting validation can return buyer_reason.code: "unsupported_targeting" with recovery: "correctable". Its message names the targeting field or product setting that needs attention. Update that setting and submit a new media buy. Other provider, authentication, and transport messages are not promoted into buyer-visible reasons.

Media-buy change with an unknown outcome

A media-buy update, pause, or cancel that reaches a connected ad platform can fail after the platform may already have applied part of it. When Apostra cannot confirm the change and cannot prove it was undone, the error is as follows. Today Meta and ChatGPT ads media buys report this outcome. Undoing a change is not proof on its own. If the platform timed out, returned a server error, or read back without the requested change, the original change can still land after Apostra’s undo. Apostra still attempts the undo, but it reports this outcome instead of rolled_back.

{
  "code": "SERVICE_UNAVAILABLE",
  "recovery": "terminal",
  "details": {
    "reason": "adapter_update_outcome_unknown",
    "mutation_outcome": "unknown",
    "cleanup_required": true,
    "retry_safe": false
  }
}

Do not resend the same change. Resending it could apply it twice. Read the media buy’s current state first (for example with Get media buy status), then submit any further change as a new request. Branch on details.reason and details.retry_safe, not on the message. This is the update counterpart of the create-time scope3_create_uncertain and scope3_mutation_uncertain outcomes described in Create media buys.

Media-buy request stopped before reaching the ad platform

When Apostra rejects a create_media_buy or update_media_buy before sending anything to the connected ad platform, the error carries details.mutation_outcome: "not_dispatched". Nothing in the request was applied on the platform. Pinterest, Snap, LinkedIn and ChatGPT ads media buys report this outcome whenever Apostra can prove nothing was sent. A few rejections cannot be proved, for example a failure while Apostra serializes concurrent changes to the same account or media buy. Those carry no mutation_outcome.

{
  "code": "INVALID_REQUEST",
  "recovery": "correctable",
  "details": {
    "mutation_outcome": "not_dispatched"
  }
}

What this means for a retry with the same idempotency key:

update_media_buy: the key is released. Resending with the same key runs the request again instead of returning the saved failure. Fix what the error names first; an identical request usually fails the same way.
create_media_buy: the key is released only when recovery is correctable. Otherwise the same key keeps returning the saved failure, so send the corrected request with a new key.

A Snap create_media_buy that Apostra deleted from Snap after a later step failed reports details.mutation_outcome: "rolled_back" instead: the request reached Snap and was removed. The idempotency key is kept. A ChatGPT ads media buy does the same. A create_media_buy that failed after the campaign was written reports rolled_back once Apostra has archived the campaign and read the archive back, and unknown when it could not. A update_media_buy that failed after part of it was applied puts back the campaign budget and targeting, the ad group settings and the creative it changed, and reports rolled_back when the platform reads back the original values. If the campaign was active, it stays paused after the failed update; resume it once you have checked the buy. An error without mutation_outcome may have reached the ad platform. Do not assume a retry is safe; read the media buy’s current state first. Branch on details.mutation_outcome and recovery, not on the message.

Flight window elapsed on an approval-gated storefront

Some publisher storefronts hold an incoming create_media_buy for a human operator to approve before it reaches the seller. Approval and dispatch are separate moments: the buy waits in the operator’s queue, and only once it is approved does the platform send it on. That wait can be long — minutes while an operator reviews, or longer if the publisher has paused intake. If a buy’s end_time has passed by the time it is dispatched, no seller can accept it. The platform stops before contacting any seller and fails the buy’s task with details.forward_error.code of flight_window_elapsed:

{
  "code": "INVALID_REQUEST",
  "message": "This media buy's flight ended at 2026-05-08T23:59:59.000Z and can no longer be sent to a source. Submit a new media buy with a current flight window.",
  "recovery": "correctable",
  "details": {
    "reason": "storefront_forwarding_failed",
    "source_outcome": "precondition_failed",
    "forward_error": {
      "code": "flight_window_elapsed",
      "message": "This media buy's flight ended at 2026-05-08T23:59:59.000Z and can no longer be sent to a source. Submit a new media buy with a current flight window."
    }
  }
}

How to recover. Submit a new create_media_buy with a current end_time. Retrying the same buy will not help and is not attempted on your behalf: this media buy is finished, and the platform will not send it to a seller under any later condition. The recovery of correctable refers to the request — a corrected flight window succeeds — not to the buy that failed. Why you may not have seen it before. A buy in this state used to be retried against the seller for several hours, rejected each time, and then left approved but never placed with no reason recorded. It now fails on the first dispatch attempt with the message above, so the flight window is the thing you fix rather than something you have to infer from silence.

A start_time that has merely slipped into the past is not an error. The platform re-reads the flight window at dispatch and sends a past start as "asap" — start on acceptance — so a buy whose start passed while it sat in the approval queue still runs. Only an elapsed end_time ends the buy.

Approved buy that could not be sent yet

After an operator approves a buy on an approval-gated storefront, sending it to the seller can fail for a reason that may clear on its own or once someone acts, for example a seller that has not yet linked your account to its inventory source, an advertiser not yet mapped to an ad account on a storefront that books through an ad platform such as Meta or TikTok, or a seller that is briefly unreachable. The platform retries the same buy for up to six hours; time the publisher spends with intake paused does not count. While it retries, the buy’s create_media_buy task stays submitted and the buy stays pending. When a later attempt succeeds, the task completes as normal. Do not resubmit the buy during this window: a new create_media_buy creates a second buy. If no attempt succeeds before the window ends, the platform stops retrying and the task fails:

{
  "code": "INVALID_STATE",
  "message": "Media buy mb_abc was approved, but the storefront could not send it to the seller before its retry window ended, and has stopped retrying it.",
  "recovery": "correctable",
  "suggestion": "Ask the seller to resolve the cause reported on the media buy, then submit a new media buy.",
  "details": {
    "reason": "forward_retry_window_lapsed"
  }
}

correctable refers to a corrected, new request, not to the media buy that failed. A failure that no retry can fix, such as every source refusing the request itself, fails the task on the first attempt with that diagnosis, the masked details.per_source, and no retry_after.

Approved update that could not be sent yet

An update_media_buy that an operator approves is sent to the seller the same way, and follows the same rules. While the platform retries it, for up to six hours not counting time the publisher spends with intake paused, the update’s task stays submitted. That includes an update that has to wait for the media buy itself to settle at the seller, such as a buy the seller is still accepting or a cancellation still in progress. A later successful attempt completes the task. Do not submit the same change again during this window. If no attempt succeeds before the window ends, the platform stops retrying and the update’s task fails:

{
  "code": "INVALID_STATE",
  "message": "The update to media buy mb_abc was approved, but the storefront could not finish sending it to the seller before its retry window ended, and has stopped retrying it.",
  "recovery": "correctable",
  "suggestion": "Ask the seller what is blocking changes to this media buy, then submit the update again.",
  "details": {
    "reason": "forward_retry_window_lapsed"
  }
}

An update that no retry can fix fails its task on the first attempt: a payload the media buy cannot take, such as packages that match none of the buy’s packages, fails with INVALID_REQUEST, and every source refusing the update fails with that diagnosis and the masked details.per_source. Neither carries retry_after. Except for a cancellation, the platform does not send an update again after its task has failed, so submitting it again does not apply it twice. A cancellation that cannot be sent leaves the media buy running; the seller sees the blocked cancellation in its approval queue.

Plan-gated refusals

When Apostra refuses an action because of an organization’s plan, the message says the plan is the reason, and details.planSwitch gives a typed next step so an agent can tell the person to switch plans instead of guessing. The error code and the other details fields of each refusal do not change. The field is added beside them on REST responses and in MCP structuredContent.

{
  "code": "CONFLICT",
  "message": "Adding a Buyer Account would make Acme both buy and sell. Organizations that buy and sell need an Agentic Media Company plan, or Global Market Maker by arrangement. Acme is on Listing.",
  "details": {
    "reason": "plan_does_not_cover_account",
    "nextStep": "change_plan",
    "planSwitch": {
      "nextStep": "switch_plan",
      "canAct": true,
      "actor": "billing_administrator",
      "planPricingPath": "/42/billing?tab=plan",
      "planPricingUrl": "https://app.example.com/42/billing?tab=plan"
    }
  }
}

Field	Meaning
`nextStep`	Always `switch_plan`.
`canAct`	`true` only when the caller is an administrator of the billing organization and can switch the plan now. `false` when only another administrator can, or when the check could not be completed.
`actor`	Who holds the authority: `billing_administrator` for the caller’s own billing organization, or `seller_administrator` when a buyer-side request was refused because the Seller has not selected a plan.
`planPricingPath`	The Plan & pricing tab of Plan & Billing in the app. Present only when `canAct` is `true`.
`planPricingUrl`	The same location as an absolute link. Present only when `canAct` is `true`.

These refusals carry it:

The organization’s plan does not cover the change (details.reason plan_does_not_cover_account). When the first step is to pick a different seller product, there is no plan switch.
Custom modular inventory sources need an Enterprise Merchandising plan (403, FEATURE_NOT_ENABLED on REST).
Operating agents for clients needs an active Certified Agent Partner Program entitlement.
A Seller has not selected a plan (INVALID_REQUEST, details.reason plan_selection_required). The caller cannot switch another organization’s plan, so canAct is false and there is no link.
A Seller has not met the prerequisites for running briefs (INVALID_REQUEST, details.reason seller_prerequisites_missing). details.missing lists brief_acceptance_rules, payment_authority or storefront_unmatched (the storefront handling the brief is not the Seller’s), and details.prerequisites gives each step’s nextStep. canAct is false for the caller, and the Seller’s administrator completes the steps (see Before your storefront runs briefs).

Platform policy refusal

When the platform safety policy declines a discovery brief or a campaign write, the error is INVALID_REQUEST (HTTP 422) with the message “Request declined by platform policy.”, details.reason of safety_refused, and details.policy_documentation_url. It never names the matched rule. Revise the request and retry, or contact support to ask for a review. If the check cannot run, the error is a retryable SERVICE_UNAVAILABLE (HTTP 503); for a discovery brief, details.reason is safety_check_unavailable. That is not a finding about the request: retry it after a short wait. See Request declined by platform policy.

Account type refusal

A Buyer API call needs a Buyer account, and a Seller API call needs a Seller account. A call from any other account type is refused, and the error says which. Branch on details, not on the message:

details.reason is account_type_not_allowed when the account type is refused, and account_type_unverified when the platform could not confirm the account type. In the second case nothing was decided: retry after a short wait.
details.surface is buyer or storefront, the API the call was refused on.
details.accountType is the refused account’s type: parent (an organization, which is a container and not a Buyer or Seller account), developer, buyer or seller. It is absent when reason is account_type_unverified.

On REST the refusal is 403 CUSTOMER_ROLE_DENIED (503 CUSTOMER_ROLE_UNAVAILABLE for account_type_unverified). On MCP it is the ADCP ACCESS_DENIED tool error in structuredContent. To act, switch to an account of the right type, for example a child account inside the organization.

MCP Page capability errors

Host-only Page aliases return the ADCP ACCESS_DENIED tool error when their session-bound capability is missing, expired, belongs to another Page or session, or the requested arguments fall outside that Page’s exact allowlist. The error is returned in MCP structuredContent, not the REST envelope. For an expired capability, the Page caller makes one renewal attempt with the tool associated with the same Page resource and, if renewal succeeds, retries the unchanged operation once. If renewal fails, preserve the original denial. Do not retry a wrong-resource or off-policy call through another Page. In Teach, ACCESS_DENIED also prevents the Page from rejecting a destination-owned Material candidate. Teach presents that candidate as a handoff. A direct MCP client may record rejection with public save_material; acceptance still goes through the candidate’s named canonical typed owner.

Validation errors

When request validation fails, code is VALIDATION_ERROR and details.issues enumerates every problem Zod found, with dotted field paths:

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "issues": [
        { "path": "name", "message": "Required" },
        { "path": "budget.amount", "message": "Number must be positive" },
        { "path": "flightDates.start", "message": "Invalid date" }
      ]
    }
  }
}

When a single-field check fails (e.g. a route guard), field is set instead:

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Start date must be in the future",
    "field": "start_date"
  }
}

Always render details.issues[].path in your UI — the user usually just needs to know which form field to fix.

Lists that need at least one item

Since October 27, 2026, the v2 buyer API follows AdCP 3.3 for many list fields: a list that is present needs at least one item, and an empty list is refused with VALIDATION_ERROR. To say “none”, leave the field out instead of sending []. These v2 buyer requests carry such a list:

Request	Lists that need at least one item
`POST /storefront-accounts/sync`	`accounts[].brand.countries`
`POST /products/query`	`brand.countries` and the brand-kit lists under `brand.brand_kit_override`
`POST /media-buys/batch` and `POST /discovery/{discoveryId}/products`	`targetingOverlay.collection_lists`, `targetingOverlay.collection_lists_exclude`, and the vendor brand lists on `optimizationGoals[].vendor`
`PUT /campaigns/{campaignId}` and `PATCH /media-buys/{mediaBuyId}`	the vendor brand lists on `optimization_goals[].vendor`
`POST /advertisers/{advertiserId}/property-lists`	`filters.feature_requirements[].allowed_values`

Reads do not take this rule: a response returns what is stored, so a stored empty list still comes back as an empty list.

Handling errors in client code

curl -i https://api.apostra.com/api/v2/buyer/campaigns \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertiserId": 123}'

# HTTP/1.1 400 Bad Request
# Content-Type: application/json
#
# {
#   "data": null,
#   "error": {
#     "code": "VALIDATION_ERROR",
#     "message": "Request validation failed",
#     "details": {
#       "issues": [
#         { "path": "name", "message": "Required" },
#         { "path": "budget", "message": "Required" }
#       ]
#     }
#   }
# }

async function createCampaign(body: unknown) {
  const res = await fetch("https://api.apostra.com/api/v2/buyer/campaigns", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SCOPE3_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  const json = await res.json();

  if (!res.ok) {
    const { code, message, field, details } = json.error;

    switch (code) {
      case "VALIDATION_ERROR":
        // Surface details.issues[] in your form UI
        throw new ValidationError(message, details?.issues ?? []);
      case "RATE_LIMITED":
        // Honor Retry-After header
        const retryAfter = Number(res.headers.get("Retry-After") ?? "5");
        throw new RateLimitError(retryAfter);
      case "NOT_FOUND":
      case "ACCESS_DENIED":
        throw new NotFoundError(message);
      default:
        throw new ApiError(code, message, field);
    }
  }

  return json.data;
}

import requests

def create_campaign(body):
    res = requests.post(
        "https://api.apostra.com/api/v2/buyer/campaigns",
        json=body,
        headers={"Authorization": f"Bearer {SCOPE3_API_KEY}"},
    )
    payload = res.json()

    if not res.ok:
        err = payload["error"]
        if err["code"] == "VALIDATION_ERROR":
            issues = err.get("details", {}).get("issues", [])
            raise ValidationError(err["message"], issues)
        if err["code"] == "RATE_LIMITED":
            raise RateLimitError(int(res.headers.get("Retry-After", "5")))
        raise ApiError(err["code"], err["message"])

    return payload["data"]

Don’t pattern-match on message text — message strings may be reworded for clarity. Always branch on error.code (and on HTTP status as a fallback).

Retrying safely

RATE_LIMITED, INTERNAL_ERROR, SERVICE_UNAVAILABLE, and FX_RATE_UNAVAILABLE are transient — retry GETs with exponential backoff. For creation/mutation requests after a 5xx, prefer to surface the error rather than auto-retry, since duplicate-create protection isn’t enforced server-side. VALIDATION_ERROR, NOT_FOUND, FORBIDDEN, ACCESS_DENIED, CONFLICT, and SPEND_DENOMINATION_UNRESOLVED are terminal — don’t retry until the input or state changes. CONFLICT has two narrow automatic-retry reasons, and they are machine-readable rather than a matter of reading the message. name_creation_in_progress means another writer holds that name and has not finished. adoption_in_progress means the source-identity state is still settling: another adoption is completing or its blocker changed during classification. Retry the identical request shortly for either reason. Every other adoption reason requires a changed input or state: name_taken and name_creation_abandoned require choosing another name or archiving the blocker; adoption_abandoned means a stale creation marker never cleared (an asset row may already exist), and adoption_asset_unavailable means the finalized asset is no longer usable; adoption_name_mismatch requires using the existing creative name or renaming it separately; and source_delivery_revoked or source_deletion_requested requires uploading a new source. MCP classifies those action-required cases as correctable, not transient. Branch on details.reason, never on the message. A storefront’s AdCP update_media_buy on a Meta media buy, when it is sent straight to Meta rather than held for seller approval, returns CONFLICT if the request’s revision no longer matches the buy. details.mutation_outcome is not_dispatched: nothing in the request was applied on Meta. MCP classifies it as transient in the AdCP sense: re-read the buy with get_media_buys, check its current state, and resubmit with the returned revision. Resending the identical request unchanged fails again.

A 5xx status does not by itself mean “retry”, and a 4xx does not mean “never”. On MCP surfaces, branch on the recovery classification (transient / correctable / terminal) that every error carries; on REST, branch on code. A read that fails because stored data is inconsistent — such as SPEND_DENOMINATION_UNRESOLVED — is terminal even though nothing about your request was wrong, and an automatic retry loop on it will simply burn quota.

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Error envelope

HTTP status codes

Common error codes

Buyer identity and storefront account errors

Buyer-actionable errors on `create_media_buy`, `update_media_buy`, `sync_creatives`

Media-buy change with an unknown outcome

Media-buy request stopped before reaching the ad platform

Flight window elapsed on an approval-gated storefront

Approved buy that could not be sent yet

Approved update that could not be sent yet

Plan-gated refusals

Platform policy refusal

Account type refusal

MCP Page capability errors

Validation errors

Lists that need at least one item

Handling errors in client code

Retrying safely

​Error envelope

​HTTP status codes

​Common error codes

​Buyer identity and storefront account errors

​Buyer-actionable errors on create_media_buy, update_media_buy, sync_creatives

​Media-buy change with an unknown outcome

​Media-buy request stopped before reaching the ad platform

​Flight window elapsed on an approval-gated storefront

​Approved buy that could not be sent yet

​Approved update that could not be sent yet

​Plan-gated refusals

​Platform policy refusal

​Account type refusal

​MCP Page capability errors

​Validation errors

​Lists that need at least one item

​Handling errors in client code

​Retrying safely

Error envelope

HTTP status codes

Common error codes

Buyer identity and storefront account errors

Buyer-actionable errors on `create_media_buy`, `update_media_buy`, `sync_creatives`

Media-buy change with an unknown outcome

Media-buy request stopped before reaching the ad platform

Flight window elapsed on an approval-gated storefront

Approved buy that could not be sent yet

Approved update that could not be sent yet

Plan-gated refusals

Platform policy refusal

Account type refusal

MCP Page capability errors

Validation errors

Lists that need at least one item

Handling errors in client code

Retrying safely