Why a conversion did not count
Read the XD-reason header (or the pixel's debug=1 JSON) to see why a pixel or server-to-server conversion was not counted, what each reason code means, why repeated test conversions vanish, and how to decode a click ID or tracking link.
A conversion pixel or postback that “did nothing” almost always says why on its response. This page lists the reason codes the ad server returns, how to read them, and why repeated test conversions can vanish. To set up the tracking in the first place, see Get the pixel and S2S tracking code; to run a test conversion, see Test a conversion.
Who this is for
Anyone integrating or testing conversion tracking — network managers and the advertiser’s own
developers. Reading the response needs no permission in Epom: it is whatever your browser, your
server or curl receives from the ad server.
Read why a conversion did not count
The pixel always answers 200 OK with a 1×1 GIF, so nothing in the picture tells you whether
the conversion landed. The outcome is on the response instead, in an XD-reason header —
present on every conversion response, success included, from the cookie pixels
(/action.gif, /action.js) and from the server-to-server endpoint (/at) alike.
On the image pixel you can also add debug=1 to the URL and get the outcome as a small JSON
body instead of the image (any non-empty value works; the JS pixel and the S2S endpoints do not
serve it):
curl -s 'https://ads.example.com/action.gif?key=<key>&debug=1'
{"reason":"no-cookie","counted":false,"description":"No click or view cookie reached the ad server - the browser dropped it, or this user never saw the ad."}
counted is true only when the conversion was added to the advertiser’s totals — which is
ok and nothing else. The codes you meet while integrating:
XD-reason | What happened |
|---|---|
ok | Counted. |
expired | A click or view matched but fell outside the action’s attribution window. Recorded as a diagnostic, not counted. |
no-cookie | No click or view cookie arrived — wrong browser, cookies cleared, or a consent tool dropped it. |
no-match | Cookies arrived, but none of them belongs to a creative of this campaign — or of any campaign sharing its conversion-tracking alias. Usually the tag sits on a page reached without seeing the ad. |
already-tracked | The same click or view already produced this conversion; the repeat is deduplicated. On the pixel the check is server-side as well as cookie-side, so it holds even when the visitor’s browser could not store the tracking cookie. Clicking the ad again starts a new chance to convert. On a postback the same reason means something narrower — see the corner case on repeats below. |
window-disabled | That event type has a zero-length window on this action, so it never converts. |
cookie-data-missing | A cookie matched, but it carried no ad data to build the conversion from. |
key-unknown | The key= value does not resolve to a conversion action. key= is the pixel parameter, so this is a stale or mistyped copy of a pixel code block — a postback never sends it. |
action-data-missing | The request named no conversion the ad server could read — no subId, no key + click-id pair, or a value in one of them it could not decode. Almost always a truncated postback URL, or a placeholder that resolved to nothing so the parameter arrived empty; a double-encoded click id does it too. Check what your server actually sent, not what the template says. |
The rest all say the same thing in different words — the entity named by the cookie or the click id is not live in ad serving: deleted, or with conversion tracking switched off. A cache reload lags a settings change by up to ten minutes, so one of these right after an edit may simply be the ad servers not having caught up.
XD-reason | Which entity |
|---|---|
pair-unknown | The key and the click id both parsed, but together they name no conversion action. |
action-unknown | The conversion action. |
banner-unknown | The creative — unknown, or conversion tracking is off for it. |
campaign-unknown | The campaign — unknown, or conversion tracking is off for it. |
advertiser-unknown | The advertiser. |
placement-unknown | The placement. |
country-unknown | Not an entity: the country of the conversion could not be resolved from the request. |
error | Not an entity either: the ad server failed while processing the conversion. Worth reporting. |
Two more headers ride along on the same response:
| Header | What it says |
|---|---|
XD-attribution | Which cookie jar answered, as an attribution type (POST_CLICK, POST_VIEW, and the expired variants). Set on the cookie pixels only, and worth reading when a landing page’s click id went missing: the pixel reads both jars and a click beats a view, so a conversion you assumed was post-view is frequently a post-click whose easclid= never arrived. |
XD-warning | A parameter the ad server did not use on a conversion it otherwise counted. Today the only value is payout-word-refused. Unlike XD-reason these accumulate — one response can carry several. |
Outcomes that predate the reason header still emit their original single-purpose flag alongside
it, valued 1, for anything already parsing them:
XD-reason | Legacy flag |
|---|---|
action-data-missing | XD-data-key |
pair-unknown | XD-pair |
action-unknown | XD-action |
placement-unknown | XD-placement |
banner-unknown | XD-banner |
campaign-unknown | XD-campaign |
advertiser-unknown | XD-advertiser |
country-unknown | XD-countryData |
error | XD-exc |
Reading these headers from JavaScript on the advertiser’s own page works: all of them, XD-warning
included, are named in Access-Control-Expose-Headers. A plain new Image().src = … pixel cannot
read response headers at all — use fetch(), or just debug=1 from the command line.
Corner case: on the server-to-server endpoints the HTTP status is almost the same answer —
/atreplies404when nothing was logged and200when something was. The exception is the one that matters: an expired conversion logs a diagnostic row, so it answers200whileXD-reason: expiredsays it was not counted. Read the header, not the status.
Decode your tracking links
A click ID and an encrypted tracking link do not say anything to the eye: AQ8… and
https://ads…/zG7… are just strings. To see what one carries — which banner, placement, campaign
and action, which country and ad request, when it was minted, which VAST event fired it — decode
it over the API or ask the AI assistant.
- REST:
POST /rest-api/tracking-decode.dowithinputset to the text. One call takes up to 64 KB: click IDs and URLs one per line, a postback or landing URL, a whole VAST response, or the value of the ad server’subvc/ubvvisitor cookie copied from your browser. OnlyPOSTis accepted — aGETanswers405— so what you paste never travels in a query string, where web server and proxy logs would keep the visitor data in it. See the Actions API reference. - MCP / AI assistant: the
tracking_decodetool, with the same text. See MCP server.
Both need the Action Tracking: Server-to-Server permission (ACTION_TRACKING_S2S) on your
role, the one that shows the postback URLs that carry click IDs. Without it the API answers 403
naming that permission, and the AI assistant does not offer the tool.
Each item comes back with its kind — click ID, impression, click, VAST tag, VAST event, conversion postback or pixel — its parameters by name, the click IDs inside it (those in a click’s landing URL included), and the names of the entities it refers to. Up to 50 items are decoded per call; the answer says when there were more.
- Only your own items. An item is decoded when it names an advertiser, campaign or creative
your account may view, or a placement on a site you may view. Any other answers this item belongs
to an account you cannot view, without saying whose; one that names no banner, campaign or
placement at all is not decoded either. An encrypted link is judged only by what was sealed into
it: a query added after it, your own
c=or click ID included, does not count. - Each side’s details only with access to that side. An item has an advertiser’s side
(campaign, creative, advertiser, action, the DSP and its win price, the landing URL) and a
publisher’s side (placement, page URL, app package, channel, traffic source, the publisher’s
custom parameters). You see the publisher’s details only when your account may view the site of
the placement, and the advertiser’s only when it may view the campaign or creative. Of a side you
may not view only its ids are shown, and
hiddensays which side was held back — Publisher details hidden: no access or Advertiser details hidden: no access. An advertiser reading its own click therefore sees the placement id but not the page or app it came from, and a publisher reading a click on its own placement sees the campaign and creative ids but not the DSP or the price. The time, country, transaction and consent belong to the ad event and show either way. The same rule applies to each click ID in a link and to a query added after an encrypted link. A parameter the ad server does not write itself counts as the advertiser’s in a postback or conversion pixel and as the publisher’s in an ad request; anywhere else it shows only to an account that may view both sides. - What was sealed, and what was added. Anyone can add a query after an encrypted link, and the
ad server reads an added parameter over the sealed one of the same name. The item’s parameters
and entity names are what your network sealed; the added query comes back apart, under
appended, with each click ID in it decoded on its own terms. - Each click ID on its own. A click ID inside a link is decoded only when it names an entity your account may view; otherwise it answers the same refusal in place of its fields, while the rest of the link is still shown. The VAST event a postback stands for is named only from such a click ID, and only when your role may view its action.
- Only your own names. In a decoded item, an entity your account cannot view reads not visible to your account instead of its name. A parameter that appears more than once counts by its first value, the one the ad server reads, and at most ten campaigns, creatives and placements are read from one item.
- No visitor identifiers. The visitor’s IP and origin IP, user agent (an overriding
ovrduatoo), cookie and device ids, location and consent strings readpresent (hidden), also when they arrive as custom parameters such asifa,iosadvid,andadvid,googleAdId,udid,latitude,gpporpreviewIp. The echo of what you pasted is masked the same way. If an investigation needs them, ask Epom support. - One answer per item. An altered click ID, one cut short or one minted by another network is reported on its own line; the rest of the text is still decoded.
- Cookie values, entry by entry. The
ubvc(click) andubv(view) cookies hold one entry per recent click or view, and spell a version 2 click ID with.and~in place of-and_. Each entry of a pasted value — as stored, percent-encoded or afterubvc=— is an item of its own, decoded like the same click ID taken from a URL, and a single click ID copied from the cookie reads the same way.
Corner cases and gotchas
Corner case: repeated test conversions from the same machine can silently disappear. The pixel counts one conversion per click or view: fire it twice for the same click and the second is a duplicate, never shows up in reports, and answers
already-tracked. A “Duplicate conversion window (per IP)” on the action removes further repeats from the same address. Wait out the window, click the ad again, or test from another machine.Server-to-server postbacks are different: there the only identity is the one your partner sends, so repeats are counted unless you tick Reject duplicate conversions on the action and your network runs duplicate detection — the checkbox is not even offered when it does not.
The landing-page snippet posts to the same endpoint but refuses the repeat before it leaves the browser, so a second fire of the same event on the same click is not counted whatever those two settings say. See Install the landing-page helper.