Reject codes

After this page you can look up any number the RTB surface gave you, tell at a glance whether it is yours to fix or somebody else's, and write code that branches on the outcome rather than on a sentence.

When a ping gets no bid, the response carries a reject object: a numeric code, a short machine-readable reason and a description in words.

{
  "ok": false,
  "bidId": null,
  "payout": 0,
  "payoutCents": 0,
  "reject": {
    "code": 1006,
    "reason": "outside_hours",
    "description": "Outside hours of operation"
  },
  "auctionId": "AU-100483"
}

A no-bid is a 200. Three refusals keep their own status so an HTTP client notices them — 429 for 1024, and 409 for 1025 and for a caller who already holds a live bid on the campaign — and the authentication refusals at the foot of this page are 401 and 403.

The campaign, the account and the lane

Too many requests

The caller

At post time

The request itself

Authentication

These are refused before an auction exists, so they carry no reject object — the body is { "ok": false, "error": "…", "message": "…" }, with code on the four signature failures. Each one is still a row in the ping ledger.

Warnings

A warning never changes the outcome. It exists so an integrator can see a problem before it becomes a support ticket. Warnings arrive as a warnings array of { code, description } and are present only when there is something to say.

Why a bid did not become a call

A bid that was made and then lost carries a loss code. It is on the bid in the ledger and is sent to external bidders on a loss notice. 0 is a win, which keeps "did this bid convert" a single comparison.

What a payout depends on

A bid carries a terms array. Those terms are frozen onto the bid when it is quoted and read back by settlement, so the conditions that decide the money are the ones you were quoted — not whatever the campaign says by the time the call ends.

"terms": [
  { "code": 101, "description": "Call must connect" },
  { "code": 100, "description": "Minimum connected duration 90 seconds", "seconds": 90 },
  { "code": 110, "description": "Duplicate callers are not paid within 86400 seconds", "seconds": 86400 }
]

Reading a refusal from the other side

The descriptions above are written for the publisher who receives them, which is why a handful are in the second person. A workspace reading its own ping ledger sees the same codes reworded — 1014 reads "The publisher's cap for this campaign was filled" — because "your" would point at the wrong party. The code is the same number either way.

Each refusal also carries an owner: whose move it is. It is the fastest way to triage a bad afternoon.

A worked example

Northwind Media send 400 pings on a Friday and win 90. Their ping summary ranks the refusals:

1. 1008 state_not_targeted, 210 pings, owner publisher. They are sending states the lane does not buy. That is theirs to filter, and it is most of the gap.
2. 1006 outside_hours, 61 pings, owner network. Their evening traffic arrives after the lane closes. They ask the buyer, who widens the hours.
3. 1011 no_bids, 33 pings, owner demand. Nobody wanted those callers. Nothing to fix.
4. 1024 rate_limited, 6 pings, owner publisher. A burst went over the minute limit. They honour Retry-After instead of retrying immediately.

Two of the four are theirs, one is the buyer's and one is nobody's. The conversation that follows is about the two that can be changed.

Next steps