Understanding API Responses

HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:

Successful Response (200 OK)

When bids are available, the API returns HTTP 200 with this structure:

{
  "id": "request-123",
  "seatbid": [
    {
      "bid": [
        {
          "id": "",
          "impid": "1",
          "price": 0.0246025,
          "adm": "<script>...ad creative markup...</script>",
          "w": 300,
          "h": 250,
          "ext": {
            "adid": "das,1849766,1027111",
            "actioncount": "https://tracking.example.com/..."
          }
        }
      ]
    }
  ],
  "cur": "USD"
}

Response Fields

• id (string) - Matches your request ID
• seatbid (array) - Array of seat bid objects
• seatbid[].bid (array) - Array of bid objects
• cur (string) - Currency (always "USD")

Bid Object Fields

Each bid object contains:

• id (string) - Bid identifier (may be empty)
• impid (string) - Which impression this bid fulfills (matches request)
• price (number) - Bid price in CPM (Cost Per Mille)
• adm (string) - Ad creative markup (HTML/JavaScript)
• w (number) - Creative width in pixels
• h (number) - Creative height in pixels
• ext (object) - Extension fields

Extension Fields

• ext.adid (string) - Internal ad identifier (format: "das,[id1],[id2]")
• ext.actioncount (string) - Impression tracking URL
• ext.dsaurl (string, optional) - DSA transparency URL

No Bids Available (204 No Content)

When no ads match your request, the API returns HTTP 204 with an empty body:

HTTP/1.1 204 No Content

Common reasons:

• No active campaigns match targeting
• All campaigns exhausted budget
• Bid prices below floor
• User reached frequency cap

What to do: Display fallback content or house ads.

Multiple Bids Response

When requesting multiple impressions, you may receive multiple bids:

{
  "id": "multi-request",
  "seatbid": [
    {
      "bid": [
        {
          "impid": "header",
          "price": 0.05,
          "adm": "<script>...header ad...</script>",
          "w": 728,
          "h": 90
        },
        {
          "impid": "sidebar",
          "price": 0.03,
          "adm": "<script>...sidebar ad...</script>",
          "w": 300,
          "h": 250
        }
      ]
    }
  ],
  "cur": "USD"
}

Match bids to impressions using the impid field.

Common Error Codes

Understanding Bid Prices

Bid prices are in CPM (Cost Per Mille - cost per thousand impressions):

{
  "price": 0.0246025
}

This means $0.0246025 per 1000 impressions, or approximately $0.000025 per single impression.

Response Extensions

The response may include additional extension fields:

{
  "ext": {
    "protocol_version": "2.5",
    "gctx": "context-string",
    "debug_info": {
      "candidates_count": 1
    }
  }
}

Extension Fields

• ext.protocol_version - OpenRTB protocol version
• ext.gctx - Internal context string
• ext.debug_info - Debugging information