Error codes

Every AutoSugges runtime response that fails carries a typed code field in its JSON body — switch on it, never on the message text, which is deliberately generic and constant per code so it cannot be used to probe for a private list's existence.

Every AutoSugges error code, its HTTP status, whether a caller may safely retry, the exact message returned, and what to do about it
Code	HTTP status	Retryable	Message	What to do
invalid_key	401	No	The publishable key is missing, invalid or revoked.	The publishable key is wrong, revoked or rotated. Check the key in your AutoSugges dashboard. Do not retry with the same key.
origin_not_allowed	403	No	This origin is not allowed for this key.	The requesting origin is not on this key's allow-list. Add the origin in the dashboard. Not billed.
invalid_list	404	No	That list is not available for this key.	The key resolves to no list, or the list was deleted. Nothing to retry.
subscription_required	403	No	That list is not available for this key.	The list is shared and this consumer has no active subscription to it. Subscribe, or use a list you own.
list_not_published	409	No	That list has no published version yet.	The list exists but has never been published, so there is no artifact to serve. Publish it once from the dashboard.
token_expired	401	No	The access token has expired.	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	401	No	The access token is invalid.	The access token failed signature or scope verification. Mint a new one; do not retry the same token.
quota_exceeded	200	No	The query allowance is exhausted.	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	200	No	The query is shorter than this list allows.	The query is below the list's `minQueryChars` (`details.minQueryChars`). Do not issue the request at all until the input reaches it — the SDK already refuses locally. Not billed.
query_too_long	400	No	The query is longer than this API allows.	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	400	No	The request could not be understood.	The request is malformed — a missing parameter or an unusable value. `details` names what. Fix the call; retrying unchanged cannot help.
rate_limited	429	Yes	Too many requests.	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	403	No	The verification challenge failed.	A bot challenge was not satisfied on a session-establishing surface. Re-present the challenge. Not billed.
publish_validation_failed	422	No	The list did not pass publish validation.	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	500	Yes	The list could not be compiled.	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	503	Yes	That list is temporarily unavailable.	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	404	No	That resource no longer exists.	The resource was deleted. Stop requesting it; there is nothing to retry.
invalid_domain	400	No	That domain cannot be used.	The submitted domain or slug is not valid or is reserved. Choose another.
domain_validation_failed	409	No	The domain could not be validated.	A custom-domain DNS or TLS validation did not complete. Re-check the DNS records shown in the dashboard, then revalidate.
internal_error	500	Yes	Something went wrong.	An unexpected server-side failure. Report the `requestId` from the response. Retry at most once, with backoff.