OpenRTB loss reason codes (lurl)

How a loss notice works

A bidder that wants loss telemetry puts a loss notice URL in bid.lurl, with macros where the facts should go:

{
  "id": "1",
  "impid": "imp-1",
  "price": 9.43,
  "lurl": "https://dsp.example.com/loss?auction=${AUCTION_ID}&reason=${AUCTION_LOSS}&mtw=${AUCTION_MIN_TO_WIN}",
  "adm": "..."
}

If the bid loses and the exchange supports loss notices, it expands the macros and calls the URL: ${AUCTION_LOSS} becomes the reason code, ${AUCTION_PRICE} is only meaningful on wins, and exchanges that support ${AUCTION_MIN_TO_WIN} fill in the price that would have turned the loss into a win. The macro reference covers the full substitution table.

Three caveats before you build dashboards on this. Loss notices are optional, so absence of a notice is not evidence of a win. Exchanges differ on which codes they send and when (some batch, some sample, some only send economic losses). And the code list itself lives in the OpenRTB 3.0 document, which is where 2.6 points for both this list and the no-bid reason codes; the values below come from that list.

The loss reason code table

Reading the ranges

The list is organized in blocks, and the block tells you who owns the fix:

• 1-10: your response is broken. These are hygiene failures the exchange found in the bid itself: unparseable response, missing price, missing markup, a dealid that does not exist. Every one of these is fixable unilaterally, and most are visible in the response before it leaves your servers. The bid response anatomy page lists what a well-formed bid carries.
• 100-104: auction economics. Floors, higher bids, deal priority, seat blocks. A spike in 100 or 101 means your pricing model and the floor signals disagree; a spike in 103 means open-auction bids are losing to deals and the inventory you want has moved behind PMP.
• 200-215: creative filtering. The bid was fine; the creative was not. Size, format, security, category, attributes, app bundle. These are the codes worth alerting on, because they are systematic: a creative that trips 207 (Not Secure) or 203 (Size Not Allowed) will lose every auction it enters until someone fixes the creative or the targeting.
• 500 and up: exchange-specific. Meaningless without the exchange's documentation. If a partner sends them, get the mapping in writing.

Debugging with loss codes

1. Separate the ranges first. A falling win rate from 102 is a pricing problem; the same fall from 200-range codes is an ops problem. Aggregating them into one loss metric hides both.
2. Treat 3, 7, 8, 9 as build failures. They mean the exchange received something malformed. Validate the exact response you send: the tester accepts bid responses as well as requests, and flags missing required fields and type mismatches against the spec.
3. Cross-check 4 (Invalid Deal ID) against your deal sync. It usually means a deal was paused or renamed on the exchange side while your bidder kept bidding into it.
4. Use min-to-win where you can get it. In first-price auctions, ${AUCTION_MIN_TO_WIN} on losses is the cleanest shading signal the protocol offers; it turns 102 from a verdict into a calibration point. See the first-price vs second-price guide for how shading fits in.

FAQ

Validate the bid before the exchange grades it

Codes 1 through 10 are the exchange telling you your response failed validation. rtblint runs the same class of checks locally: paste a bid response into the tester or run rtblint validate response.json via the CLI to catch missing prices, absent markup, and malformed fields before an exchange turns them into loss codes.