Skip to documentation
AdQuestDocs

Errors

Error codes returned by the API and SDK, and what to check for each.

On this page

Error codes and next steps

Code / symptomWhat to check
INVALID_API_KEYKey value, environment, rotation and disabled / revoked status.
INACTIVE_PLATFORMBoth approval and activation are required.
ORIGIN_FORBIDDEN / PACKAGE_FORBIDDENThe platform’s Where AdQuest may appear list: exact origin or package, and the hosted embed origin.
PARTICIPANT_AUTH_REQUIRED / PARTICIPANT_EXPIREDMint or refresh through your authenticated backend; use the same user and platform.
PARTICIPANT_BLOCKEDResolve participant account status; refreshing alone will not help.
HOST_CONTEXT_INVALID / HOST_CONTEXT_TOO_LARGEContext shape, permission values and the 8 KB limit.
QUEST_NOT_FOUNDQuest ID, visibility, lifecycle and participant eligibility.
TIMER_NOT_STARTED / invalid watch evidenceStart the quest and satisfy actual duration / progress requirements.
INVALID_ANSWERThe selected option, required questions and verification settings.
ALREADY_COMPLETEDRefresh participant state instead of granting again.
CAPACITY_EXHAUSTED / RATE_LIMITEDWait or resolve delivery limits. Back off instead of retrying in a loop.
INSUFFICIENT_TOKENS / LOTTERY_CLOSED / ENTRY_LIMIT_REACHEDRefresh lottery state and balance before another confirmed purchase.
NETWORK_ERROR / CORS failureAPI 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.

Using the wrong key

CodeHTTPWhat it means
PLATFORM_KEY_USED_AS_SECRET401You sent the public API key (aqk_) as the Secret Key. Use the aqs_ key on your server.
WEBHOOK_SECRET_USED_AS_SECRET401You sent the webhook signing secret (whsec_) as the Secret Key. It only verifies incoming webhooks.
PARTICIPANT_AUTH_REQUIRED401The Secret Key or participant token is missing or does not match.

Quest evidence errors

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.

CodeHTTPRaised when
ACTIVITY_GOAL_NOT_MET422A complete on an event quest before its goal is reached. AdQuest settles it by itself when it is.
NOT_VISIT_QUEST400You called visit on a quest that is not a visit quest.
INVALID_REDIRECT422The quest’s destination link is not valid.
REFERRAL_REQUIRED422A complete on a referral quest before enough invited friends have signed up.
CUSTOM_EVIDENCE_MISMATCH422The evidence_type is not the one the custom quest uses.
CUSTOM_CALLBACK_REJECTED422Your callback URL did not answer 2xx with verified: true, redirected, or answered more than 8 KB.
CUSTOM_CALLBACK_UNSIGNABLE422The platform has no Event signing secret, so AdQuest cannot sign the callback. Generate one.
CUSTOM_CALLBACK_RATE_LIMITED429Too many callback checks for this participant. Wait a minute.
QUEST_BUDGET_EXHAUSTED422The quest’s budget is used up.
QUEST_SETTLEMENT_FAILED422The reward could not be settled. Retry later or contact support.
PREVIEW_READONLY403A theme preview cannot complete quests, enter lotteries or submit claims.

Lottery and claim errors

Lottery and claim routes return the code in data.code. They have no top-level code.

CodeHTTPRaised when
LOTTERY_NOT_FOUND404The lottery does not exist or is not visible to this platform.
LOTTERY_NOT_AVAILABLE404Country policy hides the lottery from this participant.
LOTTERY_CLOSED422The lottery is not open for entries.
ENTRY_LIMIT_REACHED422The participant reached the lottery’s entry limit.
INSUFFICIENT_TOKENS422The participant does not have enough tokens.
DUPLICATE_PURCHASE409The idempotency_key was already used for a different lottery or participant.
CLAIM_NOT_AVAILABLE404 or 422The claim is not the participant’s (404), or it is closed or expired (422).

Server route errors

Every /server route returns the code in code and data.code. Each reported activity has its own result, with its own codes: see Report activities.

CodeHTTPRaised when
SERVER_AUTH_REQUIRED401No signature and no Secret Key, or the public API key is wrong. The public key alone is never enough.
SIGNATURE_INVALID, SIGNATURE_EXPIRED401X-AdQuest-Signature does not match the raw body, or its t is more than 5 minutes off.
PLATFORM_INACTIVE403The platform is not approved and switched on.
FULFILLMENT_NOT_FOUND404The fulfillment is not one of your platform’s.
FULFILLMENT_CONFLICT409The fulfillment already has the other final answer. Acknowledged and rejected are both final.
ACTIVITY_NOT_FOUND404No reported activity has that id.
RANGE_TOO_LONG422A reconciliation range of more than 93 days.

Streak errors

CodeHTTPRaised when
STREAK_SETTLES_ITSELF422You called complete on a streak quest. Days come from your server’s activity and the last day settles the quest.
STREAK_DAY_LOCKED422The next day is not unlocked yet.
STREAK_FROZEN422The streak is frozen after a missed day.
TIMEZONE_ABUSE422The participant’s timezone changed in a way that looks like abuse.

Activity errors in the dashboard

CodeHTTPRaised when
ACTIVITY_NOT_REGISTERED, EVENT_NOT_REGISTERED422A quest or step counts an activity your platform has not registered.
ACTIVITY_QUEST_PRIVATE_ONLY422A quest proven by activities belongs to one platform: make it private.
ACTIVITY_IN_USE409A live quest counts this activity: only its label and link can change, and it cannot be deleted.

Winner contact errors

CodeHTTPRaised when
WINNER_CONTACT_INVALID422The email is not valid.
CLAIM_NOT_AVAILABLE404The claim does not exist or is not available.

Next steps

Something unclear, missing or wrong here? Tell us