For AI agents: this page is also available as Markdown at /docs/limits-and-errors.md. Every docs page is: add .md to its URL. llms.txt lists them all.

Limits and errors

WarpSearch has two kinds of limits. Plan limits depend on your plan and are not listed here as numbers, because they change: see the free tier and /pricing, or call GET /v1/usage to see yours. Fixed limits are properties of the engine and are the same on every plan. This page lists both, then the errors you get when a request breaks one.

Plan limits

Limit What happens when you exceed it
Collections Creating another answers 403 limit_exceeded.
Stored data Writes are throttled or refused according to your plan. Check usage in the console.
Documents and bytes per write request 413 request_too_large. Send smaller batches.
Hits per search (limit) and result window (offset + limit) 422 limit_exceeded.
Facets per request and buckets per facet 422 limit_exceeded. A size of -1 is capped at the plan's limit.
Query size, clause count and nesting depth 422 limit_exceeded. Query size counts filters, variables, facets and sorts as well as the query.
Time per request 504 timeout.
Requests per second and at the same time 429 rate_limited or too_many_concurrent_requests.
Regex and wildcard queries 403 forbidden when your plan does not include them.
Response size and monthly returned data Per-response caps apply on the free tier, and returned data is billed beyond the allowance.
Exact (brute-force) vector search Disabled above a vector count on the free tier.

See API keys, roles and rate limits for how rate limits behave and Pricing for the cost side.

Fixed limits

Limit Value
Collection name ^[a-z][a-z0-9_]*$
Collection description 2000 characters
Collection metadata 16 KB of JSON
Field name ASCII letters, digits and _, starting with a letter, no __, at most 127 bytes
Indexed term length 255 bytes. Longer keyword values are kept distinct, but pattern queries may not reach the cut-off tail.
Vector dimensions 8192
kNN num_candidates 10000. k is bounded by your result window.
Date histogram buckets 5000, and 1024 when the histogram has metrics or nested facets
Fuzzy edit distance 2
cardinality precision_threshold 40000
Percentile compression 20 to 1000
Native query variables Values only: never a field name, never syntax

Error format

REST errors from /v1 follow RFC 9457 problem details, with the content type application/problem+json:

{
  "type": "https://warpsearch.io/docs/errors/limit_exceeded",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "limit_exceeded",
  "detail": "offset + limit exceeds the result window for your plan",
  "request_id": "7d1c1a3e0f9b4c2e"
}

Branch on code, show detail to a developer, and include request_id when you contact support. Responses to calls on the Elasticsearch, OpenSearch and Solr compatible endpoints use those APIs' own error shapes with the same HTTP status, so existing clients keep working.

Error codes

Status code Meaning What to do
400 invalid_request Malformed body, unknown request field, or no documents. Fix the request.
400 invalid_collection_name The name breaks the naming rule. Use lowercase letters, digits and _, starting with a letter.
400 invalid_mapping The mapping is malformed or empty, or uses an unsupported type. Check the field types.
400 invalid_field A field name does not exist or is not allowed. Check the collection's fields with GET /v1/collections/{c}.
400 query_error The query could not be parsed or is invalid. Read detail, which names the position.
400 unsupported_feature The query uses something WarpSearch does not offer. See the status notes in Query languages and Feature status.
401 Missing or invalid credentials. Check the key.
403 forbidden Your role is too low for this call. Use a key with the role named in detail.
403 limit_exceeded You have reached your plan's collection limit. Delete a collection or change plan.
403 no_organization The signed-in user has no active organization. Pick an organization in the console.
404 not_found No such collection or document, or you hold no role on it. Check the name and your key.
409 already_exists A collection with that name exists. Choose another name.
413 request_too_large The request is over the plan's documents or bytes per request. Split it.
422 limit_exceeded A plan limit on a search, such as page size, result window, facets or clauses. Reduce the request, or change plan.
429 rate_limited Over your request rate. Wait for Retry-After.
429 too_many_concurrent_requests Too many requests at once. Retry shortly.
429 too_many_auth_failures Too many failed authentications from your address. Fix the credentials.
429 resource_exhausted The search backend is overloaded. Retry later with backoff.
499 canceled The client closed the connection.
500 internal Something failed on our side. Retry, then report the request_id.
503 warming_up The collection is loading after being idle, or waiting for capacity. Retry after Retry-After.
503 unavailable The search backend is temporarily unavailable. Retry with backoff.
504 timeout The request ran past your plan's time limit. Narrow it with filters or a time range.

Two codes appear in the body of a write response rather than as the HTTP error: unknown_field (the document uses a field that is not mapped and has no type suffix) and the per-document codes in errors. See Ingesting documents.

Retrying

Situation Retry?
429, 503, 504 Yes, with exponential backoff and jitter, honoring Retry-After.
500 Yes, a few times.
Network error or timeout on a write Yes. Writes with ids replace, so repeating them is safe.
400, 401, 403, 404, 409, 413, 422 No. The same request will fail again until you change something.

A 413 write is not retried as is: split the batch first. A 422 search is not retried either: lower the limit, the page depth or the facet size.

Warnings

Not every problem is an error. When WarpSearch approximates something instead of rejecting it, the response succeeds and carries a warnings array (and a Warning: 299 header on compatible endpoints). Examples are a score approximation in a multi_match, an analyzer that fell back to standard, a clamped percentile compression or an ignored index setting. Read warnings while you are developing: they tell you where WarpSearch differs from the engine you are migrating from.

Common situations

View this page as Markdown