Troubleshooting

Every failure we can identify, grouped by what you were trying to do. Start with the first section — the failures there stop a first integration dead.

Each area page also carries its own troubleshooting table. This page is the cross-cutting index.

Nothing works yet

These account for most failed first integrations. Work down the list in order.

Symptom	Cause	Fix
The wall link lands the visitor on your homepage	The API key is missing or unknown.	An unrecognised key is rejected at validation and the browser is redirected home, so a typo looks like the wall "not working" rather than an error. Verify the key character by character.
`403 App not found or inactive`	The key is valid but the app is not approved.	New apps are created `pending` and do not function until an administrator approves them. Wait for approval, then retry.
The wall renders but you have earned nothing, and nothing looks wrong	`userId` is missing or empty in the iframe URL.	The wall endpoint tolerates an empty user ID, but the tracking endpoint the wall calls when a visitor clicks does not. No click is recorded, so no conversion can occur — and nothing on the page tells you. Add a distinct, stable `userId` for every visitor.
Rewards shown to visitors are absurdly small or large	The exchange rate is inverted.	The field is your currency units per one US dollar. EUR is about `0.92`, JPY about `143`, INR about `83`. The rate the form suggests follows the opposite convention — do not accept it unedited.
Tracking fails for some visitors only	Their `userId` contains characters that corrupt the wall's own URLs.	The wall substitutes your user ID without escaping it. `&`, `+`, `#`, `?` and spaces all break it. Use letters, digits, `-` and `_`, or percent-encode the value yourself.
The wall shows offers for the wrong device	Targeting follows the visitor, not your app.	Offers are matched on the visitor's detected country and device. Your app's platform setting does not filter offers, and its currency only affects displayed amounts.

API errors

Response	Meaning	Fix
`401` `INVALID_API_KEY`	The app credentials did not match.	`GET /api/v1/offers` requires both `apiKey` and `apiSecret`. The app must also be approved. Send both, from your server — the secret must never appear in client-side code.
`422` `INVALID_PARAMETERS`	A parameter failed validation.	The `message` field contains the per-field errors. Common causes: `country` must be exactly two characters; `platform` must be `web`, `android` or `ios`; `limit` must be 1–100; `sort` must be `payout_desc`, `payout_asc` or `newest`.
`200` with an empty offer list	No offers matched.	Narrowing came from country or device detection, a category filter, or offers having reached their cap. Try omitting `country` and `platform` to confirm offers exist at all.
`429`	Rate limited.	60 requests per minute. Add caching and back off.
`404` `Offer not found or inactive`	The offer ID is wrong or the offer is no longer active.	Fetch the offer list again; offers come and go.

Click tracking

Symptom	Cause	Fix
`403 Invalid API key or app not approved`	Unknown key, or the app is not approved.	Check the key and the app's approval status.
`403 Access Denied: Suspicious Activity Detected`	A fraud rule fired on the click.	The most common triggers are many clicks from one `userId` or IP in a short window, and several accounts behind one device. Genuine blocked traffic needs your operator to review it.
Validation error instead of the advertiser page	The click arrived without a usable `userId`.	The wall builds the tracking URL from whatever you supplied. If the user ID was missing, the parameter arrives empty and the request fails. This surfaces to the visitor as a broken new tab while the wall itself looks healthy.
Clicks are recorded but conversions never arrive	The network has not posted a conversion yet.	Conversions arrive from the offer network, not from you. Check the clicks report to confirm traffic is arriving, then wait. Persistent silence on a specific offer usually means that advertiser stopped converting.

Postbacks

Every attempt is recorded under Reports → Postbacks, with the resolved URL and the exact error. Check there before anything else.

Symptom or log entry	Cause	Fix
"No postback URL configured"	No URL is saved on the app.	Save one on the app's detail page.
"Blocked: postback URL is not a public http(s) address"	The host resolves to a private, loopback or link-local address.	Use a publicly reachable HTTPS endpoint. `localhost` is permitted for development. The block is not retried.
Timeout	Your endpoint did not answer within 10 seconds.	Respond faster. Nothing is retried automatically — re-send from the test tool.
Non-2xx recorded	Your endpoint answered with an error or redirect status.	Any `2xx` counts as success. Redirects are followed and the final status recorded.
No postback ever arrives for locker conversions	Correct behaviour.	Content and Link Locker conversions never post back. Use the locker's statistics page.
`{currency}` or `{timestamp}` arrives literally	Those macros do not exist.	Unsupported macros are not replaced and not flagged — they are sent verbatim. Remove them from your URL.
`{offer_id}` is identical across different offers	It is the network ID, by design.	Use `{offer_name}` to distinguish offers.
The same conversion arrives more than once	Expected.	A conversion notifies on creation and again when its status resolves. Deduplicate on `{transaction_id}`.
Amounts in `{reward}` do not reconcile	The field's meaning depends on the network type.	For an API-network conversion it is your USD share; for an iframe partner-wall conversion it is the end user's reward in your currency. See Postback Setup.

Content and Link Lockers

Symptom	Cause	Fix
Dark full-screen overlay containing an error	The Content Locker JavaScript loader is not working on this build.	It points at a path the server does not serve. Use the iframe method instead.
An unlock event never arrives	The lockers send no browser events.	There is no `postMessage` and no unlock callback — nothing emits one, so a listener will never fire. Poll the locker's `/progress` endpoint instead.
One visitor unlocks it for everyone	`uid` was not passed.	Without it, visitors are grouped by IP, so a shared network shares one session. Pass a unique `uid`.
Visitors must re-unlock every visit	The `uid` or device fingerprint changes between visits.	Keep `uid` stable across sessions.
Link Locker visitors cannot finish the required offers	The offer list holds at most three entries.	Set the required conversions to 3 or fewer.
Locker endpoints start returning errors under load	Rate limiting.	All public locker endpoints share 60 requests per minute per IP. Poll `/progress` no more than once every few seconds.
Locker previews show offers that look invented	Sample data substitution.	When no offers match the filters, the preview substitutes placeholder offers with made-up amounts. Never rely on preview figures.

Wallet, payouts and deposits

Symptom	Cause	Fix
No withdrawal form or button	Direct withdrawal requests are disabled.	Expected. Payouts are generated automatically each month. Set an active payout method so they can be sent.
Earnings accumulate but nothing is paid	One of: no payout method, an inactive one, a total below the threshold, or an invoice awaiting approval.	Check the withdrawal history page for the invoice status. `skipped` means the threshold was not met and the balance carried forward.
Balance and reported earnings disagree	Rejections and pending conversions.	Rejections reduce the balance immediately; pending conversions count toward earnings but pay nothing. Your balance is authoritative.
Deposit page missing from the menu	Menu layout.	Go directly to `/user/wallet/deposit`.
Paid but the balance did not change	The deposit is not `completed`.	Check the deposit history. Manual methods stay `pending` until an administrator approves them.
Paid more than the amount requested	Provider fees.	Deposit fees are added on top of your amount. Withdrawal fees are deducted from the payout. The directions are opposite.

Reporting quirks

These are limitations of the current build rather than faults in your integration. They are listed so you do not lose time chasing them.

Observation	Why	Workaround
Total Earnings includes rejected conversions despite its label	The query applies no status filter.	Subtract the lost revenue from the rejected conversions report, or filter conversions by status.
The earnings chart ignores the selected date range	It is anchored to the trailing window.	Read the chart as a trend, and use the headline figure for the range.
Filtering clicks by IP returns nothing	The query targets a column the click table does not have.	Browse the click list unfiltered.
The clicks list shows no IP and marks everything unconverted	Both columns render from fields the table does not contain.	Use the conversions report to determine what converted.
No eCPM, EPC, CTR, impressions or exports	Not implemented.	Do not plan reporting around them.

When to contact your operator

Some things only your platform operator can resolve:

Your app has been pending approval for an unreasonable time, or was rejected.
Genuine traffic is being refused by fraud detection and needs reviewing.
A payment method you expect is missing from the deposit page.
A payout invoice was rejected, or has been pending far too long.
Monthly payouts are not being generated at all on your installation.
The Content Locker JavaScript loader needs to be fixed.

When you report a problem, the most useful details are your app name, the UUID of any locker, the exact error text, the time it occurred, and whether it reproduces. Support requests are also available from inside your publisher account.