Errors

Every error is answered with the Elasticsearch error envelope and the matching HTTP status. Client libraries that understand Elasticsearch errors understand Ferroseek’s.

{
  "error": {
    "root_cause": [{ "type": "…", "reason": "…" }],
    "type": "…",
    "reason": "…"
  },
  "status": 400
}

Errors that Elasticsearch raises while executing on a shard, such as a bad value for a field’s type, are wrapped as a single-shard cluster wraps them: a top-level search_phase_execution_exception with "reason": "all shards failed" and the real error in root_cause and failed_shards.

Unsupported features fail loudly

When a request uses something Ferroseek does not implement, the answer is a 400 whose reason starts with [ferroseek] unsupported: and names it. Nothing is ever silently ignored, so a request that works against Ferroseek means the same thing against Elasticsearch.

{
  "error": {
    "type": "illegal_argument_exception",
    "reason": "[ferroseek] unsupported: query [wildcard]",
    "root_cause": [{ "type": "illegal_argument_exception", "reason": "[ferroseek] unsupported: query [wildcard]" }]
  },
  "status": 400
}

Limits that Elasticsearch does not have answer in the same style: [ferroseek] … exceeds the limit of [N].

Status codes and types

Status	Type	When
400	parsing_exception	Malformed query DSL, unknown query or aggregation type
400	x_content_parse_exception	Unknown field inside a known object; bool nested deeper than 20
400	json_parse_exception, json_e_o_f_exception	The body is not valid JSON
400	illegal_argument_exception	Invalid values, unknown routes, unknown URL parameters, unsupported features, Ferroseek’s own limits
400	search_phase_execution_exception	Shard-level failures: wrong field type, unparsable value, result window too large, too many clauses
401	security_exception	Missing or wrong credentials (standalone Worker with authentication)
404	index_not_found_exception	The index named in the path is not the loaded one
404	(none)	_doc/{id} for an unknown id: {"found": false, …}
405	illegal_argument_exception	A known route with the wrong HTTP method
413	illegal_argument_exception	Request body larger than 256 KiB
500	exception	The engine trapped while answering; the instance is replaced
500	settings_exception	The standalone Worker is misconfigured (for example, only a username is set)
503	too_many_buckets_exception	More than 65,536 aggregation buckets
503	index_unavailable_exception	The index failed to load; the next request retries

With the official client

The official client turns error responses into errors.ResponseError, with the status in err.meta.statusCode and the body in err.body:

import { errors } from "@ferroseek/client";

try {
  await client.search({ index: "products", query: { wildcard: { name: "sho*" } } });
} catch (err) {
  if (err instanceof errors.ResponseError) {
    console.error(err.meta.statusCode, err.body.error.type);
    // 400 illegal_argument_exception
  }
}

The repository’s npm run client:check runs the same calls, including several failing ones, through the official 7.17 and 8.x clients against Ferroseek and against Elasticsearch, and reports any call whose outcome differs.