Errors

Request IDs

Every /v1 response, success or error, carries an X-Request-Id header, and every JSON error body carries the same value as requestId. Quote it when you contact support: it is how we find your request in our logs and error reports.

To use your own id, send an X-Request-Id header of 8 to 128 characters from A-Z a-z 0-9 . _ : -, such as a UUID or your trace id. Headband echoes it back. Anything else is replaced with a generated req_ id. Browser code can read the header: it is listed in Access-Control-Expose-Headers.

curl -si https://headband.dev/v1/search \
  -H "Authorization: Bearer $HEADBAND_SEARCH_KEY" \
  -H "X-Request-Id: 7d1f0c9e-checkout-search" \
  -H "Content-Type: application/json" \
  -d '{"index": "products", "q": "shoes"}'

HTTP/2 200
x-request-id: 7d1f0c9e-checkout-search

Request Error Codes

Errors in the request itself, on the /v1 routes:

The search codes come with a message that names the field and how to set it up. See Search Errors.

422 partial_failure

Adding or bulk importing documents on an Elasticsearch or Typesense index, or deleting documents by id on Elasticsearch, returns 422 when the engine rejected some documents and wrote the rest. Only the written documents count toward your usage. Meilisearch writes are asynchronous tasks, so a rejected Meilisearch document shows up in the task (GET /v1/tasks/:taskUid) instead.

Visor writes one batch atomically: a bad document fails the whole request with a 400 naming it, and nothing is written. A batch over the engine's size limit is 413 payload_too_large; send it in smaller batches.

{
  "error": "1 of 3 documents failed",
  "code": "partial_failure",
  "failed": 1,
  "errors": [
    {
      "id": "2",
      "status": 400,
      "type": "mapper_parsing_exception",
      "reason": "failed to parse field [price] of type [long]",
      "retryable": false
    }
  ]
}

failed counts every rejected document; errors lists at most 100 of them. Each entry has the document id (or null when unknown), the engine's per-document status, a type, a reason, and retryable. A retryable entry (engine status 429 or 5xx) may succeed if you send that document again; a non-retryable one needs the document fixed. Resend only the failed documents: the others were written.

When every failed document is retryable, the body also has "retryable": true and the response a Retry-After: 1 header. On POST /v1/bulk/stream the stream has already answered 200, so the same failed and errors fields arrive on the batch_complete and complete events, and complete carries "code": "partial_failure" when anything failed.

413 payload_too_large

A REST request body can be at most 4 MiB (4,194,304 bytes). Every /v1 route answers a larger body with 413 payload_too_large as JSON, before it reads the body, and nothing is written. The check reads the declared Content-Length: a body sent without one is cut off by the hosting platform at about 4.5 MB, with a plain error and no JSON code. Split large imports into batches under the limit, as the import script does.

{
  "error": "Request body is 6 MB, over the 4 MB limit. Split the documents into smaller batches of under 4 MB each (about 2 for this one) and send them one request at a time.",
  "code": "payload_too_large",
  "maxBytes": 4194304,
  "receivedBytes": 6291456
}

502 engine_auth_failed

The search engine refused the credentials Headband holds for it. Your Headband API key is fine; retrying with another key will not help. If your project brings its own engine (BYOE), the host or API key saved in the project's engine settings is wrong, expired or lacks permission: update it in the dashboard. On a Headband-hosted engine it is our problem, and we are alerted.

409 index_managed_by_sync

Sync keeps this index up to date from a Postgres source, so Headband refuses direct writes to it: adding or deleting documents, bulk imports, settings changes, deleting the index, and alias flips. A direct write would be overwritten by the next change on the source. Change the sync definition instead, or delete the synced index and keep the engine index to manage it yourself. See Sync.

429 and Retry-After

A 429 means either Headband's rate limit or the search engine's. Both send a Retry-After header with the seconds to wait when one is known; for the engine's own limit it is passed through as the engine sent it. Wait that long before retrying. A 429 with code usage_limit_exceeded is different: a plan limit was reached, so retrying will not help until the limit resets, you free up room or you upgrade. On the Free plan the limits are searches, stored data and projects. Paid plans bill overage for searches and stored data instead, so at most their project limit can return it. At the monthly search cap the body also has resetsAt, and Retry-After is the seconds until then.

The rate limit on each plan's pricing card (searches and writes a second, code rate_limited) covers POST /v1/search, POST /v1/multi-search, where each query counts, and document writes through /v1/documents. Other routes have a fixed limit per key instead, the same on every plan: for example 100 requests a minute shared by /v1/bulk, /v1/bulk/stream, document writes, settings changes and creating or deleting an index, 300 a minute for POST /v1/hybrid-search, 500 a minute for POST /v1/experiments/events, and 1,000 a minute for POST /v1/ai/search, which shares one budget with search and multi-search.

503 and 504

Through the REST API, the code on a 503 says why Headband could not serve the request:

A 503 from the engine itself is passed on as a 503. On Visor, a 503 that may succeed unchanged (storage_unavailable, search_queue_full) carries Retry-After: 1. search_timeout carries none, because the same search would hit the same deadline. On a dedicated engine's own endpoint, the gateway answers 503 instance_waking with Retry-After: 2 when a wake takes longer than the plan's hold (10 seconds on Free, 25 seconds on paid plans), and 503 instance_unavailable when the engine cannot be started or reached. Through the REST API the hold on a paid plan is 30 seconds.

503 instance_unavailable when a host cannot be reached

When the server hosting a dedicated engine cannot be reached, every REST route that uses the engine answers the same way, on Meilisearch, Typesense, Elasticsearch and Visor alike: search, multi-search, documents, indexes, settings and tasks. A refused or dropped connection, a connection that takes more than 5 seconds to open, and a host that answers it does not have the engine loaded yet all give this answer. Answers the engine itself gives, such as a 400 for a bad filter or a 404 for a missing index, are passed on unchanged. An engine with a ready read-only copy on the other server differs for searches and multi-searches. Once its server is marked unreachable, they go straight to the copy. Before that, a failed search is retried once on the copy, so a search can still get this answer. Its other routes always get it.

HTTP/1.1 503 Service Unavailable
Retry-After: 2

{
  "error": "The engine for this index is not available right now. Try again shortly.",
  "code": "instance_unavailable"
}

Headband checks every host from outside every 30 seconds. After three failed checks in a row the host is marked unreachable. Requests for its engines then get this answer at once, with Retry-After: 30, without waiting on the host. The engine shows "state": "unavailable" in GET /v1/instances/<id> and in the dashboard until a check passes or the engine moves. An engine on bucket storage moves to the other server by itself in about 2 to 3 minutes; the Service levels page says which engines have a copy and what happens to recent writes. Retry after the pause; in multi-search, only the queries on that engine fail, each with this code. A write that got this answer after its connection dropped may still have been applied: documents are written by id, so sending them again is safe.

A 504 means the engine did not answer in time. On a dedicated engine's endpoint the gateway answers 504 engine_timeout after 30 seconds without data on a search or read, or after 10 minutes in total for anything else. Through the REST API, a 504 sent by an engine or by a dedicated engine's gateway is passed on as a 504. A write that timed out may still have been applied, so check before you send it again.

400 invalid_document_id

A document id in the URL path, as in GET /v1/documents/:docId, may only contain letters, numbers, hyphens and underscores, up to 511 characters. Anything else is rejected before it reaches the engine.

Dedicated Engine Gateway Errors

A dedicated engine's own endpoint sits behind a Headband gateway. When the gateway refuses a request, the body has error, code and message, which repeats error so the engines' official clients show it. A route_not_allowed body also has class. Errors from the engine itself pass through in the engine's own shape.

{
  "error": "missing credentials",
  "code": "missing_credentials",
  "message": "missing credentials"
}

See Dedicated Engines for the keys, routes and limits behind these codes.