Open the Page
sourceId comes from search({ "kind": "inventory_source" }). Leave it out to
open the Page with no source selected and choose one there. Only a Seller Account can
open the Page. A Buyer Account is refused with a wrong-account error.
Source activity does not prove demand. A Seller Account that is not ready can
correctly show no source calls, because work stops before a buyer request
reaches a source. Call
get_status first. Its blockers name the pre-dispatch
problem and the next tool or Page.What the Page shows
If your Agent refuses Apostra’s credential forlist_accounts, source health
shows an account reconciliation problem. Make the Agent accept the call
without a credential if it declares require_operator_auth: false, or save the
credential it needs on the source. Apostra retries automatically and clears the
problem after a successful listing.
The Page shows these sections, in this order:
- The verdict and its action. Whether buyers can buy from the source, and the one thing to do about it, such as checking again after a fix.
- Buyer requests. Whether buyer requests reach the source. When setup is incomplete, the steps still to finish are listed, and each opens Seller Setup.
- What needs your attention. Each problem you own, with the next step.
- Problems someone else has to fix. One line for each, stating the fact and who has to fix it, for example “AiOO’s delivery reporting needs a fix from its developer”. The line does not say anyone has been told or is working on it, because Apostra does not notify an Agent’s developer about a seller’s source.
- The Agent card. Which Agent powers the source, who operates it and where its certification stands.
- Reporting. Whether the source’s reporting is working, with alerts for parked or rejected Reliable Reporting registrations.
- Source settings. Turn the source on or off, manage its credentials and connect another sales agent.
Open agent
Open agent appears on a problem line and on the Agent card only when you can open that Agent. The Agent lives in a Developer account, which is often another company’s. You can open it only if you hold a role in that Developer account. Belonging to the same organization is not enough, because a person in a Seller account can have no role in the organization’s Developer account. When you cannot open the Agent, the Page shows no link.Where the technical detail went
The calls Apostra made to the Agent, their requests and responses, protocol errors, declared capabilities and request signing are for the Agent’s developer and for Apostra staff. The developer reads them on the Agent’s Activity Page, in the Developer account that owns the Agent. A seller never sees a call log, on this Page or through any other read. Canonical reporting shows each reporting obligation for the source. When a seller statement is overdue, rejected or has stopped progressing, the obligation names its exact seller account and reporting period. A statement that never arrived stays missing; it never appears as zero delivery or zero spend. When a Reliable Reporting registration is parked after repeated failures or rejected by the seller, Reporting shows the affected seller account and a redacted error summary. The Page shows up to 25 registrations in each state. Health uses one vocabulary: Healthy, Degraded, Erroring and Unknown. A source that has never been observed reads Unknown. Atimeout
condition means a call did not finish inside the observer’s time budget. It is
degraded evidence, not an error response from the source.
For a managed ad server, health follows the ad-server syncs. When a sync fails,
the next scheduled run retries it, and the source keeps the health the failure
gave it while that retry runs. Only a run that finishes changes it, so a sync
that keeps failing reads as one continuing problem, not one that clears every
time a retry starts.
When some of your products declare creative formats Apostra cannot read,
Apostra leaves those products out of buyers’ answers and records your source as
Degraded with the cause ineligible_products; your other products keep
selling, and a pending source can still be certified. Your source reads
Erroring only when none of its products can be read. The product format
check in Seller Setup names the products to fix. After you fix them, each
catalog refresh checks the formats again, so your source’s health catches up
on the next hourly recheck, or at once when you run
refresh_inventory_source_health.
Setup, request eligibility and health are separate. A degraded or erroring
source still receives buyer requests unless it is paused, not set up, or mapped
to an ineligible Agent.
A pending source
A source of a registered sales agent starts pending and goes live by itself when its agent passes certification or Apostra exempts it. Setting it toACTIVE
yourself is refused until then, so a pending source is never told to activate
itself. Every read of the source gives one next step, from what holds it back:
the diagnosis (diagnosis.nextSteps and the pending finding’s detail), the
source’s connection.nextStep, its selling.blockers, and the
Inventory source status step of get_status.
A source discovery test checks that the source answers. It does not start or
count toward certification, so it never clears a pending source.
A pending source with no registered sales agent can be set to
ACTIVE with
save_inventory_source once its endpoint and credentials work.
When a catalog fetch is empty
If a catalog that was serving products returns no products, Apostra keeps the last catalog while it checks again and sends one alert to its operations team. It clears the catalog after three consecutive empty fetches. A non-empty fetch resets that count. If the inventory source explicitly declares its catalog empty, Apostra clears it immediately.When what a source says it sells goes wrong
Source health diagnoses what each source reports, for a managed ad server and for an external Agent alike. A task is sent once and closes itself when the problem clears. A source Apostra hosts for you never creates a task.Product or signal list not refreshed
The list Apostra holds for a source is as old as its freshness bound, one refresh interval before the 24-hour limit. Buyers keep seeing the last good copy. This is Apostra’s to fix and shows only as a status line.Catalog can’t be read
Apostra tried to refresh a source’s product or signal list and the read failed. It is a task for you when:- your managed ad server rejected Apostra’s credentials. Reconnect it from the diagnosis; or
-
the source is an Agent you run and it is not answering the catalog request.
The diagnosis names the tool and the cause:
- Timed out or the connection failed. Your Agent did not finish
get_products(orget_signals) in time. Apostra waits 30 seconds for each page of products, so answer each page inside that, for example from a cache you keep current. - An error. Your Agent returned an error to
get_productsorget_signals; the diagnosis shows its code. Run the discovery test, read the error it shows and fix that response.
- Timed out or the connection failed. Your Agent did not finish
A source reports no products
The source is connected and answering, but no sellable products are mapped to it. For a managed ad server, build products from the synced inventory. For an Agent you run, the Agent answered the catalog request with no products: publish products in it, then run the discovery test.A source ends a discovery call as failed without a reason
Your Agent answeredget_products with a failed status and no error to read: no
error code and no message. The diagnosis says so, and says whether the answer
also carried zero products. Apostra cannot tell what went wrong from that, so the
fix is yours to find. Use the operation, task and debug identifiers in the
diagnosis’s technical details to find the request in your Agent’s logs, then
return a completed response with products, or an error that says why it
cannot. Run the discovery test again afterwards.
When your Agent does return an error, Apostra reads its code from the AdCP
error envelope or from the first entry of the errors array, including a bare
array of error entries. A code in the AdCP standard set is explained by what it
asks of you; VALIDATION_ERROR says only that the source rejected the request,
and points you to its message, because it does not say whose input failed. Any
other code is shown verbatim in the technical details without a classification.
Product creative formats not defined
An Agent you run declares only creative formats that its creative agent does not define, so no creative can be matched to those products. Each source is reported on its own. The fix is in the troubleshooting guide’s Product creative formats not defined section. The finding is judged on the catalog responses Apostra read from your Agent in the last 24 hours, and its time is when those responses were read. Some agents, InMobi’s for example, return different product ids for every brief, so a product from an old brief stops counting once its response is older than that. The finding clears when a newer response no longer lists the product, or when the responses age out. Products already used by a media buy are not changed. Who holds the finding depends on where the response came from. When every product it names comes from your Agent’s public catalog, the finding is yours and offers Run discovery test, which reads that catalog again. When a product comes from a response Apostra stored for a buyer’s brief, running the discovery test does not read it again, so the finding is Apostra’s: Apostra is looking into it and may ask you to correct the declaration in your Agent. You do not need to act unless Apostra asks.Source capabilities can’t be read
Apostra asks each Agent source what it supports, such as the billing methods, channels and creative handling it declares, and routes buyers to it on that basis. This diagnosis appears when that request has failed three times in a row, or when the last answer is more than two days old. Until it works Apostra keeps routing on the last answer it has, so the source keeps selling on terms that may be out of date, and a source Apostra has never read cannot be matched to buyers at all. If you run the Agent, fix it:- Run the discovery test from the diagnosis and read the error it returns.
- If the Agent rejected Apostra’s credentials, update them in the source’s settings.
- Otherwise confirm your Agent answers its capabilities request (the AdCP
get_adcp_capabilitiestool) within a few seconds.
A source’s agent asked Apostra to wait
Your Agent answered HTTP 429, or a 503 withRetry-After, which asks Apostra to
stop calling it until a time it names. The diagnosis shows an agent_waiting
finding with that time. It is an attention finding with no action, because
nothing is broken and there is nothing for you to do:
- Apostra’s scheduled checks skip the Agent until that time and call it again afterwards. The finding clears once the time has passed.
- While the wait lasts, the calls the Agent refused since it asked Apostra to
wait are not reported as errors, and the source is not shown as failing or
unhealthy. Calls that failed before then are still reported. Its health
readings record the wait as
degradedwith the AdCP error codeRATE_LIMITED. - A
RATE_LIMITEDreading with no current wait, for example after your Agent kept throttling a catalog page, is still reported as the source responding with errors. - A request a person makes still reaches the Agent. If the Agent refuses it as well, the answer says until when it asked Apostra to wait.
Retry-After.
Guaranteed buys waiting because availability could not be confirmed
For a guaranteed buy that your policy holds for review when availability cannot be confirmed, the availability check timed out or the ad server could not answer. The buy waits for your decision, and you can still approve or reject each held buy. This is Apostra’s to fix, and it clears as the held buys are decided.When Apostra tells you about a problem
When a source has a problem only you can fix, Apostra tells you in the app, by email, and in Slack if you have set Slack up. Most of these problems clear by themselves within an hour, and a broken source often fails on one check and passes the next, so Apostra waits an hour at both ends:- You are told once the problem began an hour ago. Apostra checks every 30 minutes, so the notice arrives between one hour and about an hour and a half after the problem began.
- A gap shorter than an hour does not restart that hour. A source failing on and off is told once, an hour after it first failed.
- A problem that goes away for a full hour before you are told sends nothing, so there is no “resolved” notice for it either.
- A problem that puts live buys at risk is sent at once (see the next section).
- If the problem is still there, you are reminded 24 hours and 7 days after the first notice, and then not again.
- You are told the problem is resolved once it has stayed fixed for an hour, so the notice arrives between one hour and about an hour and a half after the fix. If it fails again within that hour, you are not told again: the first notice still stands.
- If the same problem changes your storefront’s live status, that notice waits with it, and you get one email rather than two.
source.action_required and
source.action_resolved, listed in
Notifications.
When buyer accounts are waiting for your approval
If your sales agent answers a buyer’s account request withpending_approval,
someone at your company has to approve the account in your agent before it
accepts that buyer’s briefs. Here “account” means the buyer’s account in your
sales agent, not the buyer’s workspace on Apostra. Until you approve it, that
buyer’s briefs do not reach your source.
- Once an account has waited seven days, Apostra sends one notice per media source, in the app, by email, and in Slack if you have set Slack up. It says how many buyer accounts are waiting, how long the longest has waited, and who up to five of the buyers are, by the brand your agent already lists for the account.
- The notice is not repeated while the accounts in it are waiting. If a different account passes seven days in the meantime, it is not announced separately; once none of the accounts in the notice is waiting, a later account that waits seven days starts a new notice.
- Approve each account in your sales agent, or reject the ones you do not want to serve. When none of the accounts in the notice is waiting any more, Apostra sends one message to say so.
- If accounts are still waiting after 21 days, Apostra’s support team follows up with the owner of your account.
source.account_approval_pending and source.account_approval_answered.
When an ad-server connection fails while you have live buys
If the connection to your ad server stops signing in (for Google Ad Manager, the service account is no longer an active user in your network), your inventory, orders and the status and delivery reporting for your buys stop syncing. Only you can restore access. A buy is live when it is active, or accepted and starting within 24 hours. When live buys depend on the failed connection, the failure is critical for you:- The diagnosis names how many live buys and how much booked spend are at risk.
- Your source-health task is urgent, and the notification is sent at the error status. It is re-sent on the usual schedule and sent again as critical if live buys start to depend on a connection you were already told about.
- If you have an Apostra Slack channel, the Apostra assistant writes to it about the failure.
- Apostra’s support team is told once, with your account and the affected buys named, so someone can help you restore access.
- Buyers with a live buy on your storefront see that your status and reporting for that buy are temporarily unavailable. They are never told which ad server it is.
When a change drops a format option a live buy uses
A media buy keeps the product’s format options as they were when the buyer selected the product, and a creative can pin one of those options by its id. When a catalog refresh drops an option, re-keys it to a new id, or changes it so it no longer accepts everything it did, the live buys that still carry the old option keep sending it. Your sales agent no longer recognises it, so their creative syncs fail, including creatives that were already approved. Apostra does not block the refresh: your catalog stays as you published it. Instead, for each changed product that a live buy (booked and not ended or canceled) still depends on, it records a finding on the source and opens a work item for you. The finding names the product, the old option and the option that replaced it, the affected buys and the creatives pinned to the old option. It closes by itself the next time a refresh of that product leaves no live buy on a lost option, for example when you restore the old option. Apostra’s operations team is alerted once for each change. A change that only widens an option, such as adding a delivery type to its accepted list while it keeps its id, raises neither the finding nor the alert, because every creative the old option accepted is still accepted. Any other change to what an option accepts is treated as one that may reject creatives.Repair a missing Agent link
When an active external-Agent source has no registered Agent relationship, the source’s owner can create or attach the Agent from this Page. This is the only write the Page owns, andopen_page carries no input for it. The person who
owns the source does it in the Page. Credentials and authority changes stay
human steps in the Page and never pass through a model.
The Page attaches only a Sales Agent your organization owns, whether it sits in
this account or in another account of the same organization, such as its
Developer account. The source must connect to an external Agent. Managed and
ESA sources are refused. An Agent that belongs to another organization is
refused too; connect a certified partner’s agent through its connection
form. An Agent that declares both product
paths needs one chosen for the source. Attaching the same Agent again does not
create a second link.
Connect a sales agent
The Page’s Connect another action in Setup opens the Connect sales agent task. It lists your organization’s own sales agents and the certified partner agents your account can connect through, with a Sign up link where a partner offers one. See Connect to a partner agent.Authorize an OAuth source
When a source’s Agent signs in with OAuth, its credentials show Authorize. It opens the Agent’s consent page in a new tab, and Apostra stores the tokens it receives and uses them when it calls the Agent. I’ve authorized — refresh re-checks the source afterwards. Starting the authorization is a step in the Page, not a model-visible tool.Read the same evidence without the Page
V3 has typed reads and one action beside the Page:refresh_inventory_source_health works only on an external sales-agent source.
Managed and modular sources have their own diagnostics. It runs on a source that
is ACTIVE or PENDING.
Who has to act on a finding
Each health row, finding and operation indiagnostics.sourceHealth names an
owner, the role that has to act:
How a source’s delivery is read
On an ad-server source, theget_media_buy_delivery row in
diagnostics.sourceHealth.health carries deliveryRead, which says how the
sales agent gets the source’s delivery and when Apostra last read it:
A source with no ad-server connection has no
deliveryRead. For when Apostra
reads Google Ad Manager delivery, see
How often Apostra reads GAM delivery.
Refresh a source’s health
A failed check counts against a source until the same check records a new result. After you fix your agent,refresh_inventory_source_health runs the
checks again so the fix shows without waiting for a scheduled check. A source
that a failed check moved to PENDING can run both checks, so a passing refresh
is how it becomes eligible for ACTIVE again. Buyers still see a source’s
catalog only while the source is ACTIVE. It runs two checks, one at a time, so
they never open two connections to your agent together:
Each entry in
checks has an outcome:
The top-level
outcome, operation and evidence fields describe the
get_products check. readiness is read after both checks. When
readiness.canTransact is false, readiness.reason says why, in the words
get uses for the same source: a source that is PENDING reads “pending:
waiting for certification”. A passing check does not make a source sell, so
outcome: "passed" can sit beside a blocked readiness.
openFindings lists the recorded findings that still count against the
source but that a refresh cannot repeat, because each needs a buyer action or
real traffic:
An empty
openFindings with both checks passing means nothing recorded still
counts against the source. If readiness still shows a blocker, get_status
names it.
What V3 covers and what it does not
V3 opens this Page with an optionalsourceId. The Page shows the selected
source’s own tests. An agent reads the same tests with get and
kind: "inventory_source" and include: ["testRuns"] (see
Reading an inventory source).
The Page no longer lists recent composition attempts, and the Test Runs Page is
retired. Practice-brief and buyer-brief runs are RFPs, which search lists with
kind: "rfp".
Related
- Troubleshoot source problems, what each source diagnosis means and how to fix it
- Seller workflows: Add and diagnose inventory
- Diagnose third-party sales agents, which documents the health object and transport evidence in detail. It describes the v2 storefront API, which is deprecated.
- Buyer Account Mapping Page