| Code / symptom | What to check |
|---|
| INVALID_API_KEY | Key value, environment, rotation and disabled / revoked status. |
| INACTIVE_PLATFORM | Both approval and activation are required. |
| ORIGIN_FORBIDDEN / PACKAGE_FORBIDDEN | The platform’s Where AdQuest may appear list: exact origin or package, and the hosted embed origin. |
| PARTICIPANT_AUTH_REQUIRED / PARTICIPANT_EXPIRED | Mint or refresh through your authenticated backend; use the same user and platform. |
| PARTICIPANT_BLOCKED | Resolve participant account status; refreshing alone will not help. |
| HOST_CONTEXT_INVALID / HOST_CONTEXT_TOO_LARGE | Context shape, permission values and the 8 KB limit. |
| QUEST_NOT_FOUND | Quest ID, visibility, lifecycle and participant eligibility. |
| TIMER_NOT_STARTED / invalid watch evidence | Start the quest and satisfy actual duration / progress requirements. |
| INVALID_ANSWER | The selected option, required questions and verification settings. |
| ALREADY_COMPLETED | Refresh participant state instead of granting again. |
| CAPACITY_EXHAUSTED / RATE_LIMITED | Wait or resolve delivery limits. Back off instead of retrying in a loop. |
| INSUFFICIENT_TOKENS / LOTTERY_CLOSED / ENTRY_LIMIT_REACHED | Refresh lottery state and balance before another confirmed purchase. |
| NETWORK_ERROR / CORS failure | API reachability, HTTPS, origin restrictions and browser network details. |
The API can return more specific evidence errors in data.code or data.reason. If the SDK maps an unfamiliar code to UNKNOWN, inspect the response details rather than treating it as success.
| Code | HTTP | What it means |
|---|
| PLATFORM_KEY_USED_AS_SECRET | 401 | You sent the public API key (aqk_) as the Secret Key. Use the aqs_ key on your server. |
| WEBHOOK_SECRET_USED_AS_SECRET | 401 | You sent the webhook signing secret (whsec_) as the Secret Key. It only verifies incoming webhooks. |
| PARTICIPANT_AUTH_REQUIRED | 401 | The Secret Key or participant token is missing or does not match. |
Quest routes return the code in the top-level code field and in data.code. A request that fails validation is HTTP 422 unless a status is listed.
| Code | HTTP | Raised when |
|---|
| NOT_EVENT_QUEST | 400 | You sent an event to a quest that is not an event quest. |
| INVALID_EVENT | 400 | The event payload is not valid. |
| EVENT_NAME_MISMATCH | 400 | The event name is not the one the quest waits for. |
| EVENT_SOURCE_FORBIDDEN | 400 | The event source (sdk or server) is not allowed for this quest. |
| EVENT_WINDOW_EXPIRED | 422 | The event arrived outside the quest’s attribution window. |
| EVENT_CAP_REACHED | 422 | The participant reached the quest’s completion limit. |
| INVALID_EVENT_SIGNATURE | 401 | The signature of a server event does not match. |
| INVALID_DELIVERY_TOKEN | 401 | The delivery token is missing or not valid for this participant. |
| NOT_VISIT_QUEST | 400 | You called visit on a quest that is not a visit quest. |
| INVALID_REDIRECT | 422 | The quest’s destination link is not valid. |
| NOT_REFERRAL_QUEST | 422 | You attributed a referral on a quest that is not a referral quest. |
| INVALID_REFERRAL_CODE | 422 | The referral code does not exist. |
| SELF_REFERRAL | 422 | A participant used their own referral code. |
| ACCOUNT_REUSED, DEVICE_REUSED | 422 | The account or device was already counted for another referral. |
| REFERRAL_REQUIRED | 422 | The quest needs a referral attribution first. |
| QUEST_BUDGET_EXHAUSTED | 422 | The quest’s budget is used up. |
| PROGRESS_UNSUPPORTED | 422 | You sent a progress metric to a quest that does not track progress. |
| QUEST_SETTLEMENT_FAILED | 422 | The reward could not be settled. Retry later or contact support. |
| PREVIEW_READONLY | 403 | A theme preview cannot complete quests, enter lotteries or submit claims. |
Lottery and claim routes return the code in data.code. They have no top-level code.
| Code | HTTP | Raised when |
|---|
| LOTTERY_NOT_FOUND | 404 | The lottery does not exist or is not visible to this platform. |
| LOTTERY_NOT_AVAILABLE | 404 | Country policy hides the lottery from this participant. |
| LOTTERY_CLOSED | 422 | The lottery is not open for entries. |
| ENTRY_LIMIT_REACHED | 422 | The participant reached the lottery’s entry limit. |
| INSUFFICIENT_TOKENS | 422 | The participant does not have enough tokens. |
| DUPLICATE_PURCHASE | 409 | The idempotency_key was already used for a different lottery or participant. |
| CLAIM_NOT_AVAILABLE | 404 or 422 | The claim is not the participant’s (404), or it is closed or expired (422). |
| Code | HTTP | Raised when |
|---|
| STREAK_CALLBACK_NOT_FOUND | 404 | The callback token does not match a quest. |
| INVALID_STREAK_USER | 422 | The user ID is missing or not valid. |
| STREAK_DAY_LOCKED | 422 | Today’s day is not unlocked yet. |
| STREAK_FROZEN | 422 | The streak is frozen after a missed day. |
| TIMEZONE_ABUSE | 422 | The participant’s timezone changed in a way that looks like abuse. |
| STREAK_CALLBACK_REQUIRED | 422 | You called complete on a streak quest. Use the callback URL. |
| RATE_LIMITED | 429 | Too many requests. |
Something unclear, missing or wrong here? Tell us
