Skip to main content
Most integration issues come down to a handful of expected behaviors. Start here before digging deeper.

​
My ad isn’t showing

An ad serves only when both are true: its status is Approved and its subscription is active or trialing. Open the ad in your dashboard and confirm both. The most common causes:
  • Still pending. The advertiser paid but you have not approved the creative yet. See Reviewing ads.
  • Subscription lapsed. A failed payment moves the subscription out of active, so the ad stops serving even though it is approved.
  • Nothing eligible yet. With no approved-and-active ads, the API returns an empty list. That is expected, not an error. See an empty response is normal.
  • A weight.gte filter that is too high. If you request weight: { gte } above every tier’s weight, no ad qualifies. Lower the threshold or check your tier weights in Tiers.
  • Wrong identifier. The serving endpoint takes your workspace ID, not the slug. Copy it from the dashboard Install page or Settings → General.
  • Edge cache. Responses from ads/serving are cached for a few seconds, so a brand-new approval can take a moment to appear. Wait, then retry.

​
An empty response is normal

When nothing is eligible, getAds resolves to [] and getAd resolves to null. Revinel does not fall back to house ads, so your renderer owns the empty state. Render your own placeholder, or nothing. The SDK never throws on “no ads”.

​
Impressions or clicks aren’t counting

  • Rate limits. Tracking is capped at 600 impressions and 120 clicks per minute, per IP and ad. Over the limit, the event is dropped and the endpoint returns { "success": false } at HTTP 200. See Rate limits.
  • Viewability. With @revinel/react, useTracking records an impression only once the ad is actually visible (via IntersectionObserver). An ad rendered off-screen does not count until it scrolls into view.
  • Fire and forget. Tracking calls are best-effort with keepalive. An occasional dropped beacon is expected and safe to ignore.
  • Unknown ad. Posting an event for an ad ID that does not exist returns { "success": false }.

​
Checkout fails

​
A custom field value is missing on the served ad

ad.meta is keyed by each field’s stable slug. If a value is missing:
  • The advertiser left an optional field blank.
  • The field was added after the ad was created, so that ad has no value for it.
  • You are reading the wrong key. The slug is fixed when the field is created (for example bannerImage) and never changes when you rename the label. See Custom fields.

​
Reading errors

Every error is JSON with a code, status, and message. Validation failures (422 INPUT_VALIDATION_FAILED) add data.fieldErrors naming the rejected field, for example a count outside the 1 to 20 range. See the error reference.
Still stuck? Open an issue on GitHub or reach us through the dashboard.