Errors and limits

Error envelope

Every non-2xx response except event rejections uses:

{"error":{"code":"validation_failed","message":"The placement field is required.","fields":{"placement":["The placement field is required."]}}}

fields is present only for validation_failed. Branch on code; message is human-readable and may change.

Code	HTTP	When	What to do
invalid_app_key	401	Unknown app key	Check the key on the app page
invalid_session	401	Session token malformed, forged or for another app	Initialize again
session_expired	401	Session token expired	Initialize again
package_mismatch	403	Package name differs from the registered app	Fix the applicationId or the registration
app_not_approved	403	App not approved and not in test mode	Use test mode until approved
placement_not_found	404	No placement with that code in this app	Create it, or fix the code
format_mismatch	422	Requested format differs from the placement	Use the matching load method
validation_failed	422	Missing or invalid fields	See error.fields
rate_limited	429	A rate limit was exceeded	Wait for Retry-After seconds
server_error	500	Unexpected error	Retry with backoff; fall back

Event endpoints answer rejections with {"status":"rejected","reason":"..."} instead; see Events.

Rate limits

Per minute. “Network” means the client’s IPv4 /24 or IPv6 /48 (hashed). Network limits are generous because mobile carriers put many users behind one carrier-grade NAT.

Endpoint	Dimension	Limit
/sdk/initialize	network	600
/sdk/initialize	app key	3000
/ads/request	session	120
/ads/request	network	6000
/ads/request	app key	20000
/events/impression, click, reward	network	12000
/events/impression, click, reward	request id	20
/events/fallback	session / network	120 / 12000

A 429 carries a Retry-After header. Contact Qartvelo Ads if a large app needs higher app-key limits.

Fraud rules

Traffic that breaks these rules is not billed and does not earn revenue. Rejections are logged for review.

Rule	Default	Effect
Ad requests per session per minute	30	Further requests get no_fill
Impressions per placement per session per hour	Banners: 3600 / refresh seconds x 1.5 (180 for a 30 s banner). Full-screen: 60	Impression rejected suspicious
Impressions per session per hour, all placements	720	Impression rejected suspicious
Time between impression and click	At least 1 s	Click rejected suspicious
Clicks per session per hour	20	Click rejected suspicious
Session click-through rate	Above 50% once the session has 10+ impressions	Click rejected suspicious
Replays and duplicates	Always	409 duplicate
Package mismatch	Always	403 package_mismatch