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 andcode is listed in Errors:
200with emptybids— no ad this time;no_bid_reasonsays why. Show nothing.4xx— branch onerror.code, notmessage.400 invalid_requestlists what was wrong inerror.fields: fix it, don’t retry it.429— back off and retry later.5xxor 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:- Send
device.geo.country,device.typeanddevice.oson every request — the biggest lever. Without the country, every campaign that targets one is skipped; withouttypeandos, device-targeted campaigns can’t match.ipanduser_agentare only fallbacks. - Send the conversation — more of the exchange, with PII stripped, gives the auction more to match against.
- Don’t cap
title.max_charstighter than you need — every limit filters out some ads.
Support
For questions or assistance, reach out to contact@thrad.aiNext 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.
