# Errors

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

Source: https://dashboard.adquest.io/docs/errors · Audience: Developers · Section: API reference

## Error codes and next steps

| 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.

## Using the wrong key

| 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 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.

| Code | HTTP | Raised when |
| --- | --- | --- |
| ACTIVITY_GOAL_NOT_MET | 422 | A complete on an event quest before its goal is reached. AdQuest settles it by itself when it is. |
| 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. |
| REFERRAL_REQUIRED | 422 | A complete on a referral quest before enough invited friends have signed up. |
| CUSTOM_EVIDENCE_MISMATCH | 422 | The evidence_type is not the one the custom quest uses. |
| CUSTOM_CALLBACK_REJECTED | 422 | Your callback URL did not answer 2xx with verified: true, redirected, or answered more than 8 KB. |
| CUSTOM_CALLBACK_UNSIGNABLE | 422 | The platform has no Event signing secret, so AdQuest cannot sign the callback. Generate one. |
| CUSTOM_CALLBACK_RATE_LIMITED | 429 | Too many callback checks for this participant. Wait a minute. |
| QUEST_BUDGET_EXHAUSTED | 422 | The quest’s budget is used up. |
| 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 errors

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). |

## 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.

| Code | HTTP | Raised when |
| --- | --- | --- |
| SERVER_AUTH_REQUIRED | 401 | No signature and no Secret Key, or the public API key is wrong. The public key alone is never enough. |
| SIGNATURE_INVALID, SIGNATURE_EXPIRED | 401 | X-AdQuest-Signature does not match the raw body, or its t is more than 5 minutes off. |
| PLATFORM_INACTIVE | 403 | The platform is not approved and switched on. |
| FULFILLMENT_NOT_FOUND | 404 | The fulfillment is not one of your platform’s. |
| FULFILLMENT_CONFLICT | 409 | The fulfillment already has the other final answer. Acknowledged and rejected are both final. |
| ACTIVITY_NOT_FOUND | 404 | No reported activity has that id. |
| RANGE_TOO_LONG | 422 | A reconciliation range of more than 93 days. |

- [Report activities](https://dashboard.adquest.io/docs/quest-evidence/activities#results): The answer for each fact, and its codes.

## Streak errors

| Code | HTTP | Raised when |
| --- | --- | --- |
| STREAK_SETTLES_ITSELF | 422 | You called complete on a streak quest. Days come from your server’s activity and the last day settles the quest. |
| STREAK_DAY_LOCKED | 422 | The next 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. |

## Activity errors in the dashboard

| Code | HTTP | Raised when |
| --- | --- | --- |
| ACTIVITY_NOT_REGISTERED, EVENT_NOT_REGISTERED | 422 | A quest or step counts an activity your platform has not registered. |
| ACTIVITY_QUEST_PRIVATE_ONLY | 422 | A quest proven by activities belongs to one platform: make it private. |
| ACTIVITY_IN_USE | 409 | A live quest counts this activity: only its label and link can change, and it cannot be deleted. |

## Winner contact errors

| Code | HTTP | Raised when |
| --- | --- | --- |
| WINNER_CONTACT_INVALID | 422 | The email is not valid. |
| CLAIM_NOT_AVAILABLE | 404 | The claim does not exist or is not available. |

## Next steps

- [Troubleshooting](https://dashboard.adquest.io/docs/troubleshooting): Find the next action for a specific failure.
- [AdQuestError](https://dashboard.adquest.io/docs/sdk/errors): The same codes in the SDK.
