Skip to main content

Handle Timeouts Gracefully

Most requests answer well under a second, but the worst case is about 6 seconds: our own steps and the wait for demand partners are each capped. Always set a client-side timeout a little above that, and show no ad if it fires:

Respect Rate Limits

The API allows 100 requests per second per publisher. Your staging and production keys share that limit. Monitor rate limit headers:

Maintain Conversation Context

Send everything you have about the conversation: messages, a context.summary, context.keywords, or any mix. Keywords alone work if you can’t share the conversation text. Keep summaries current and keywords relevant. If you send more than the last message, keep the history accurate: same order, nothing dropped from the middle, and timestamps from when each message was actually sent. See context.

Error Handling

Treat anything other than a bid as “no ad”, and keep your UI working. Every status and code is listed in Errors:
  • 200 with empty bids — no ad this time; no_bid_reason says why. Show nothing.
  • 4xx — branch on error.code, not message. 400 invalid_request lists what was wrong in error.fields: fix it, don’t retry it.
  • 429 — back off and retry later.
  • 5xx or a timeout — skip the ad for this turn.

Maximising Fill Rate

Fill rate is the share of bid requests that return an ad. It comes from match quality, not from asking the server to serve regardless of match:
  1. Send device.geo.country, device.type and device.os on every request — the biggest lever. Without the country, every campaign that targets one is skipped; without type and os, device-targeted campaigns can’t match. ip and user_agent are only fallbacks.
  2. Send the conversation — more of the exchange, with PII stripped, gives the auction more to match against.
  3. Don’t cap title.max_chars tighter than you need — every limit filters out some ads.

Support

For questions or assistance, reach out to contact@thrad.ai

Next steps

Go live

Production key and ads.txt: the two steps before real ads serve.

Revenue & Metrics

Read your revenue and delivery numbers over the API.
Need exact fields? The API Reference has every request and response.