API reference
Errors and limits
Every error code, when it happens, and the numeric limits behind the API.
Error shape
type ApiError = {
error: { code: ErrorCode; message: string; retryAfterSeconds?: number };
};Error codes
| Code | HTTP status | When |
|---|---|---|
bad_request | 400 | The request body or parameters failed validation |
unauthorized | 401 | Missing or unrecognized key |
forbidden | 403 | The key or token does not permit this route, index or partition |
not_found | 404 | The index, record or task does not exist |
record_too_large | 400 | A record exceeds 100,000 bytes |
batch_too_large | 400 | A batch exceeds 1,000 operations or 5,000,000 bytes |
stale_version | 200 | Not 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_limited | 429 | The key or token's rate limit was exceeded; see retryAfterSeconds |
quota_exceeded | 429 | A beta quota (records, queries per month, or partitions) was exceeded |
domain_unverified | 403 | A crawl or a public-index query was attempted against a domain that has not passed domain verification |
crawl_running | 409 | A crawl was started for an index whose last crawl is still running; open that run instead, or start again once it finishes |
unavailable | 503 | A dependency could not answer in time; a search may still degrade instead of failing — see below |
internal | 500 | An 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
| Limit | Value |
|---|---|
| Record size | 100,000 bytes |
| Batch operations | 1,000 |
| Batch size | 5,000,000 bytes |
objectID length | 512 characters |
| Query length | 512 characters |
hitsPerPage maximum | 100 |
| Search candidates, typing | 200 |
| Search candidates, committed (Enter) | 500 |
| Bound parameters per database statement | 100 (batches are chunked automatically) |
| Tombstone retention | 30 days |
Beta quotas
See Limits and quotas for the three metered units (records, queries per month, partitions) and their beta values.