# AutoSugges — runtime API error codes

Every AutoSugges runtime response that fails carries a typed `code` field in its JSON body (and, through the SDK, as `AutosuggesError.code`). Switch on the code; never match on the `message` text, which is deliberately generic and constant per code.

## Complete vocabulary
- `invalid_key` — HTTP 401, not retryable. Message: "The publishable key is missing, invalid or revoked." Remediation: The publishable key is wrong, revoked or rotated. Check the key in the AutoSugges dashboard. Do not retry with the same key.
- `origin_not_allowed` — HTTP 403, not retryable. Message: "This origin is not allowed for this key." Remediation: The requesting origin is not on this key's allow-list. Add the origin in the dashboard. Not billed.
- `invalid_list` — HTTP 404, not retryable. Message: "That list is not available for this key." Remediation: The key resolves to no list, or the list was deleted. Nothing to retry.
- `subscription_required` — HTTP 403, not retryable. Message: "That list is not available for this key." Remediation: The list is shared and this consumer has no active subscription to it. Subscribe, or use a list you own.
- `list_not_published` — HTTP 409, not retryable. Message: "That list has no published version yet." Remediation: The list exists but has never been published, so there is no artifact to serve. Publish it once from the dashboard.
- `token_expired` — HTTP 401, not retryable. Message: "The access token has expired." Remediation: The access token is past its expiry. Mint a fresh one on your server and retry once. Never extend expiry on the client.
- `invalid_token` — HTTP 401, not retryable. Message: "The access token is invalid." Remediation: The access token failed signature or scope verification. Mint a new one; do not retry the same token.
- `quota_exceeded` — HTTP 200, not retryable. Message: "The query allowance is exhausted." Remediation: The allowance for this billing scope is spent. `details.scope` says which allowance — `subscription` or `key`. The response carries no items at all, real or synthetic: render an upgrade path, and do not feed it into selection analytics. It clears at the next billing period.
- `query_too_short` — HTTP 200, not retryable. Message: "The query is shorter than this list allows." Remediation: The query is below the list's `minQueryChars` (`details.minQueryChars`). Do not issue the request at all until the input reaches it. Not billed.
- `query_too_long` — HTTP 400, not retryable. Message: "The query is longer than this API allows." Remediation: The query exceeds the server maximum (`details.maxQueryChars`). Trim the input before sending; this is a malformed request, not something a user types.
- `invalid_request` — HTTP 400, not retryable. Message: "The request could not be understood." Remediation: The request is malformed — a missing parameter or an unusable value. `details` names what. Fix the call; retrying unchanged cannot help.
- `rate_limited` — HTTP 429, retryable. Message: "Too many requests." Remediation: Too many requests for this key, subscription or IP. Honour the `retryAfter` seconds in the body before retrying, and check that the input is actually debounced.
- `challenge_failed` — HTTP 403, not retryable. Message: "The verification challenge failed." Remediation: A bot challenge was not satisfied on a session-establishing surface. Re-present the challenge. Not billed.
- `publish_validation_failed` — HTTP 422, not retryable. Message: "The list did not pass publish validation." Remediation: A publish was rejected by validation (duplicates, an unresolved parent, a hierarchy cycle). The previously active version keeps serving. Fix the data and publish again.
- `compile_failed` — HTTP 500, retryable. Message: "The list could not be compiled." Remediation: Compilation of a new version failed. The previously active version keeps serving; nothing at runtime changed. Retry the publish after fixing the reported cause.
- `artifact_unavailable` — HTTP 503, retryable. Message: "That list is temporarily unavailable." Remediation: A published artifact could not be read at this edge, usually mid-propagation. Retryable: wait the `retryAfter` seconds and retry once. Do not render a partial or stale result set alongside a fresh one.
- `resource_removed` — HTTP 404, not retryable. Message: "That resource no longer exists." Remediation: The resource was deleted. Stop requesting it; there is nothing to retry.
- `invalid_domain` — HTTP 400, not retryable. Message: "That domain cannot be used." Remediation: The submitted domain or slug is not valid or is reserved. Choose another.
- `domain_validation_failed` — HTTP 409, not retryable. Message: "The domain could not be validated." Remediation: A custom-domain DNS or TLS validation did not complete. Re-check the DNS records shown in the dashboard, then revalidate.
- `forbidden` — HTTP 403, not retryable. Message: "Your role does not permit this action." Remediation: Your account is signed in but your workspace role does not permit this action. Ask an owner or admin to change your role, or use an account that has it.
- `internal_error` — HTTP 500, retryable. Message: "Something went wrong." Remediation: An unexpected server-side failure. Report the `requestId` from the response. Retry at most once, with backoff.

---
Canonical page: https://docs.autosugges.com/api-reference/errors