suo docs

Errors and limits

Every error code, when it happens, and the numeric limits behind the API.

Error shape

TypeScript
type ApiError = {
	error: { code: ErrorCode; message: string; retryAfterSeconds?: number };
};

Error codes

CodeHTTP statusWhen
bad_request400The request body or parameters failed validation
unauthorized401Missing or unrecognized key
forbidden403The key or token does not permit this route, index or partition
not_found404The index, record or task does not exist
record_too_large413A record exceeds 100,000 bytes
batch_too_large413A batch exceeds 1,000 operations or 5,000,000 bytes
request_too_large413A search or click body exceeds 16,384 bytes, or any other request body exceeds 5,000,000 bytes. The body is refused before it is parsed.
stale_version200Not an error response by itself — a stale write is accepted and reported via ignoredAsStale, not this code; reserved for a future strict write mode
rate_limited429The key, token or client IP address rate limit was exceeded; see retryAfterSeconds
quota_exceeded429A beta quota (records, partitions, indexes, keys, or queries past three times the monthly quota) was exceeded, or an index used its daily crawl allowance; see retryAfterSeconds
domain_unverified403A crawl or a public-index query was attempted against a domain that has not passed domain verification, or whose proof has since been removed
crawl_running409A crawl was started while a crawl of the same index, or of any index on the same domain, is still running; open that run instead, or start again once it finishes
unavailable503A dependency could not answer in time; a search may still degrade instead of failing — see below
internal500An unexpected server error; safe to retry with backoff

Degraded vs error

A search that cannot complete its full pipeline does not always fail outright. When a non-essential leg of the pipeline (for example, past M8, the vector leg of a hybrid search) times out, suo returns whatever it could compute — lexical-only results — with degraded: true in the response and the x-suo-degraded header, rather than an error. A hard failure, where no results can be computed at all, returns unavailable with no results and is safe to retry.

Limits

LimitValue
Record size100,000 bytes
Batch operations1,000
Batch size5,000,000 bytes
objectID length512 characters
Query length512 characters
Words searched per query10 (words after the tenth are ignored)
Longest word that gets typo correction20 characters
Filters per search10
Values in an in filter20
Facets per search10
attributesToRetrieve entries50
Search or click body16,384 bytes
Scoped token lifetime24 hours from the time it is used
hitsPerPage maximum100
Search candidates, typing200
Search candidates, committed (Enter)500
Bound parameters per database statement100 (batches are chunked automatically)
Tombstone retention30 days

Beta quotas

See Limits and quotas for the five metered units (records, queries per month, partitions, indexes, keys), their beta values, the per-IP limit on search and click requests, and how to ask for more.