Errors
This page lists the errors that the Foundation4 REST API returns: the error body, the errors of the web framework, and every message by status code with the cause and the resolution. Integrators use this page to handle errors in a client application, and operators use this page to diagnose failed requests. API conventions describes the conventions that apply to every operation.
Error body
An error from an API operation returns a JSON body with the content type application/json:
{
"error": {
"message": "Invalid metadata",
"details": {"product": "123 is not of type \"string\""}
}
}
message. The error message. The status code and the message identify the error; the API has no separate error code.details. Additional information for some errors, such as the invalid fields of a document or the identifier of an object that was not found. The field is absent when the error has no details. The type ofdetailsdepends on the error.
The messages in this page are exact, except where a part of the message is shown in angle brackets, such as <id>, which stands for a value.
Framework errors
The following errors come from the web framework before an operation runs. The API server returns each of them with the status of the framework, the JSON error body, the framework's text in message and the x-request-id header:
| Status | Message | Cause |
|---|---|---|
| 400 | Failed to parse the request body as JSON: <reason> | The body is not valid JSON. |
| 400 | Header of type `<name>` was missing | A required header is missing: x-pipeline-id on agent execution and the agent retrieval dry run, x-llm-id on agent execution and the OpenAI-compatible endpoint. |
| 400 | invalid HTTP header (<name>) | The value of x-pipeline-id or x-llm-id contains characters other than visible ASCII characters. The authentication headers report such a value with the messages described in HTTP 401. |
| 400 | Invalid URL: Cannot parse `<parameter>` with value `<value>`: <reason> | An identifier in the path is not a universally unique identifier (UUID). |
| 400 | Failed to deserialize query string: <reason> | A query parameter has an invalid value, such as a limit that is not an integer, a query parameter that takes one value is repeated, or a required query parameter is missing. |
| 404 | Not found | The path does not exist. A missing file under /assets, where the API reference pages load their scripts, returns HTTP 404 with an empty body and no content type instead. |
| 405 | Method not allowed | The path exists but does not accept the method. The allow header lists the methods that the path accepts. |
| 413 | Failed to buffer the request body: length limit exceeded | The body is larger than 10 MiB (10,485,760 bytes), the default of the setting app.max_body_bytes, or larger than the value of that setting. |
| 415 | Expected request with `Content-Type: application/json` | A request with a body lacks the header Content-Type: application/json. |
| 422 | Failed to deserialize the JSON body into the target type: <reason> | A required field is missing, a field has the wrong type, an enumerated field has an unknown value, or a configuration body holds a field that the operation does not define. The reason names the field and ends with the line and column of the error in the body. A reason about a field that is present starts with the field's path, as in name: invalid type: integer `5`, expected a string at line 1 column 10 for the pipeline body {"name": 5}. A missing field has no path prefix, as in missing field `name` at line 1 column 2 for the body {}. An unknown field is reported the same way: the reason starts with the field's path, as in color: unknown field `color`, expected one of, followed by the fields of the body. For a body that defines one or two fields, the reason ends with expected `<field>` or expected `<field>` or `<field>` instead. An unknown field inside an array starts with the index of the element, as in [0].color: unknown field `color` . |
| 422 | Failed to deserialize the JSON body: <reason> | A search request or a request that adds a document has a missing field, a field of the wrong type or an enumerated field with an unknown value. The reason names the problem without a line or column. An unknown top-level field in these requests returns HTTP 400, as listed in HTTP 400. |
| Any | The model server's body | The OpenAI-compatible endpoint returns the status and body of an error response from the model server unchanged. |
On an existing path, a request without valid authentication headers receives HTTP 401 before the framework reads the path parameters, the query or the body, so a request with several problems reports the authentication error first.
HTTP 400
| Message | Cause | Resolution |
|---|---|---|
Invalid parameter | A parameter of the operation is invalid. details.error names the problem, as listed in Invalid parameter details. | Correct the parameter named in details.error. |
Invalid metadata | The metadata of a document does not satisfy the pipeline's metadata schema. details maps each failing field to the reason. | Correct the named fields, or change the schema. |
Schema error | A metadata schema in a pipeline request is not valid, or a filter does not match the pipeline's schema, as described in Filter operators. details.error names the problem, and details.field names the field, or holds null when no field applies. For an integer filter value outside the 64-bit range, details.field holds the value, as in {"error": "Value must be a valid integer.", "field": "9223372036854775808"}. | Check the schema rules in Metadata, filters and taxonomies and the filter's field names and value types. |
Pagination error | A list request combines cursor and offset parameters, combines first with last, requests a page size outside 1 to 1000, or carries a cursor that cannot be read. details.error names the problem, such as limit must be between 1 and 1000, got 5000 or Invalid pagination request for a cursor. | Use one pagination mode, request at most 1000 objects per page, and pass cursors unchanged. |
Invalid order_by parameter | order_by names a field that the operation cannot sort by. details lists the unknown values. | Use a field that the operation sorts by. |
Classification mismatch | A new version of a document names a classification different from the classification of the document. | Delete the document and create the document again with the new classification. |
Invalid search type or parameters | A search request sets type to query. | Use similarity, mmr, search, hybrid or history. |
Unknown field `<name>` | A search request or a request that adds a document holds a top-level field that the operation does not define. details.expected lists the fields of the body. | Correct the field name, or move the field to the level where the operation defines the field, such as k inside params. |
`embedding` is not supported in pipeline searches: ... and the two other legacy parameter messages | A search request sends params.embedding or params.search_type, parameters of earlier releases. | Name the search index in params.index, or the indexes of a hybrid search in params.indexes, as described in Search requests. |
Invalid version | A version or as_of value lies outside the range of valid timestamps. | Use microseconds since the Unix epoch, as returned in version. |
Invalid prompt type | An agent's prompt has no system message or no user message, or the last message is not a user message. details.error names the problem. | Correct the order and roles of the prompt messages. |
Invalid prompt | A prompt template names a placeholder that the agent does not define, or the target of a retrieval placeholder is not a query placeholder. details.error names the missing placeholders. | Define every placeholder that a template names, and set each target to a query placeholder. |
Invalid placeholder <name> | An agent placeholder is invalid: two placeholders share the name, a retrieval placeholder has no target, a query or history placeholder has a target, or a retrieval placeholder names a search index in index or indexes. details.placeholder holds the name and details.error the reason. A k, fetch_k or lambda_mult value outside the rules of Search requests returns Invalid parameter instead. | Correct the placeholder. Agent placeholders search the pipeline's default indexes and cannot name an index. |
Invalid object type | The path of GET /permissions/{object_type}/... names an object type that does not exist. An unknown object type in the body of POST /api-keys/{id}/permissions returns HTTP 422 instead, as listed in Framework errors. | Use an object type listed in Access control. |
Invalid pipeline ID | The x-pipeline-id header of an agent request is not a UUID. | Send the pipeline identifier. |
Invalid LLM ID | The x-llm-id header of an agent execution is not a UUID. The OpenAI-compatible endpoint returns Invalid LLM ID: <reason>. | Send the LLM identifier. |
Missing required headers: either all of X-Agent-Id, X-Pipeline-Id, and X-Pipeline-Classification must be provided, or none of them | A request to the OpenAI-compatible endpoint carries some of these headers. | Send none of the three headers. |
Invalid interval format: <value>. Must be a valid Prometheus duration (e.g., 15m, 1h, 24h). | A statistics request carries an invalid interval. | Use a Prometheus duration. |
Request body must be a JSON object | The body of a request to the OpenAI-compatible endpoint is not a JSON object. | Send the chat completion request as a JSON object. |
The LLM has no model; set "model" in the request | A request to the OpenAI-compatible endpoint has no model field, and the LLM registration names no model. | Set model in the request, or register the LLM with a model. |
Invalid parameter details
details.error of an Invalid parameter error holds a message such as the following:
details.error | Cause |
|---|---|
Embedding provider '<provider>' or model '<model>' not found with the provided parameters: <reason> | The provider does not recognize the model or the parameters of an embedding model. <reason> names the problem, such as one of the three following messages. |
Unknown FastEmbed embedding model: <model> | An embedding model request names a FastEmbed model that the provider does not offer. The message ends after the colon when the request names no model. |
unknown field `<name>`, expected <fields> | The parameters object of an embedding model names a parameter that the provider does not define. The message lists the parameters that the provider accepts. |
Failed loading embedding model <model>: <reason> | The embedding model could not be loaded, for example because the deployment cannot download the model files. |
Failed to create embedding model: expected embedding size <n>, got <m> | The size of an embedding model differs from the dimension of the vectors that the model produces. |
Embedding size <n> is above the 2000 dimensions the vector search indexes support; ... | The size of an embedding model, or the dimension of the vectors that the model produces, is above 2000. The rest of the message names the remedies. |
data_files is not supported: ... | The parameters of a FastEmbed model name data_files. FastEmbed loads a model only from a single .onnx file. |
Text splitter provider '<provider>' not found or invalid parameters provided: <reason> | The gRPC service does not recognize the text splitter or the parameters. <reason> names the problem. |
<field> | A metadata index request names a field that cannot be indexed: a field that the schema does not declare, an object field or a field inside an object. details.error holds the field name only. |
An index needs at least one column | A metadata index request has an empty columns list. |
api_key cannot be empty; ... | An LLM create or change request sends an empty string as api_key. The rest of the message states how to send no key. |
Permissions cannot be granted on object type <type> | A permissions request names an object type that no operation checks, such as documents or fragments. |
At most 1000 fragment ids can be requested at once | A request for fragments by identifier names more than 1000 identifiers. |
A taxonomy entry cannot be its own parent: <field> = <value>, Taxonomy entry ... would create a cycle: ... | A taxonomy entry request adds an entry whose child equals the parent, or an entry whose child is already an ancestor of the parent. |
Missing prompt variables: <names> | An agent execution does not supply a value for every prompt variable of the agent. |
Prompts contain unfilled placeholders: <names> | A prompt still contains placeholders after the values were inserted. |
Missing target for placeholder: <name> | A retrieval placeholder of the agent names no query placeholder as the target. |
Missing embedding model ID for placeholder: <name> | A similarity or MMR placeholder without embedding runs on a pipeline that has no default vector index. |
`k` must be greater than 0, `fetch_k` cannot be smaller than `k` and the other search parameter messages | A search or an agent placeholder sets k, fetch_k or lambda_mult outside the rules, as listed in Search requests. |
No search indexer given and the pipeline has no default vector search indexer and the other search index messages | A search names no usable search index or distance strategy, as listed in Search requests. |
bm25_tokenizer requires full_text_search to be bm25 | A pipeline create request sends bm25_tokenizer without full_text_search set to bm25. |
Search indexer <id> is a default of the pipeline: ... and the other search index operation messages | A search index operation cannot run, as listed in Search index operations. |
HTTP 401
| Message | Cause | Resolution |
|---|---|---|
Unauthorized: No API Key specified. | The x-api-key header is missing. | Send both authentication headers. |
Unauthorized: No API Secret Key specified. | The x-api-key-secret header is missing. | Send both authentication headers. |
Unauthorized: the x-api-key header must hold visible ASCII characters only. | The x-api-key header value contains characters other than visible ASCII characters. | Copy the key identifier as plain text. |
Unauthorized: the x-api-key-secret header must hold visible ASCII characters only. | The x-api-key-secret header value contains characters other than visible ASCII characters. | Copy the secret as plain text. |
Invalid key ID | The x-api-key value is not a UUID. | Send the key's id, not the key's name. |
Invalid API Key or Secret | The key does not exist, the secret does not match, or the key is inactive or expired. | Check the key and the secret. |
When the API server cannot reach PostgreSQL or the Redis-compatible cache while checking the key, the request returns HTTP 503 instead, as described in HTTP 503.
Authenticate describes the authentication headers.
HTTP 403
| Message | Cause | Resolution |
|---|---|---|
Unauthorized: <permissions> access to <object type> required | The API key lacks a permission that the operation requires, or the key's classification allow-list does not cover the operation. | Grant the permission on the object or the object type, or use a key that holds the permission. |
Forbidden: an admin API key is required | A request to GET /statistics or GET /license uses a key that is not an admin key. | Use the master key or another admin key, described in Access control. |
Invalid license: Expired | The license has expired. | Install a renewed license. |
Invalid license: Exceeded("<types>") | The number of objects of the named type exceeds the license limit. While the count of a configuration object type, such as pipelines, embedding models or API keys, exceeds the limit for that type, every create and change that checks the license fails, whatever the object type. Once the number of documents or fragments reaches the limit, requests that add documents fail with Exceeded("Documents") or Exceeded("Fragments"). | Delete objects of the named type, or install a license with a higher limit. |
License limits exceeded for <type> | A create request would exceed the license limit for the object type. | Delete objects of the type, or install a license with a higher limit. |
In the permission message, <permissions> names the required permissions in words, such as read, write and execute or read, write and execute, and <object type> names the object type, such as Pipeline or API Key. details holds the following fields:
required. The required permissions, as an array such as["write"].object_type. The object type, as in the message.id. The identifier of the object, when the refusal concerns one object.error. The reason for the refusal, when the API server states one.
The following response reports a missing write permission on one pipeline:
{
"error": {
"message": "Unauthorized: write access to Pipeline required",
"details": {
"required": ["write"],
"object_type": "Pipeline",
"id": "3f0c9b6e-2d4a-4c1e-9b7f-5a8d2e6c1f04"
}
}
}
The following causes return the permission message:
- Permission. The key lacks the named permission on the object or on the object type. Access control lists the permission that each operation requires.
- Classification allow-list. The key's allow-list does not include a classification that a search names, or the classification of a document that the operation creates, reads, expires or deletes. A search names execute access, and adding a document names write and execute access, although adding a document requires execute only.
details.errorstates that the operation requires access to the classification, and names the classification of a search. A delete or an expiry names write access, anddetails.errorgives the reason of a read, as inReading this document requires access to the pipeline classification `confidential`.Operations on all documents of a pipeline require an allow-list that covers every classification of the pipeline. - Pipeline classifications.
POST /pipelines/{id}/classificationsrequires the*allow-list. Without that allow-list, the message names write access even when the key holds the permission, anddetails.errorstates that the change requires access to all classifications. - Key management. A key cannot grant or remove a permission that the key does not hold itself, and cannot delete itself. No key can delete the master key, deactivate it, give it an expiration or change its permissions, and only the master key can change its own name and description.
details.errorstates the reason, such asThe master API key cannot be deleted through the API. - Providers. An embedding model or text splitter create request names a provider on which the key lacks write permission.
- Taxonomy filters. A
$teqfilter names a taxonomy that the key cannot read.details.errorholdsFiltering with a taxonomy requires read access to it.
Most requests for a single object that the key cannot read return HTTP 404 instead, as described in HTTP 404. Reading, deleting and expiring documents, and listing the fragments of a document, return HTTP 403 when the document's pipeline exists and the key lacks the permission or the classification. Listing documents and reading fragments return HTTP 404 when the key lacks the permission on the pipeline.
HTTP 404
| Message | Cause |
|---|---|
<type> not found | The object does not exist, or the key lacks the permission to use the object. <type> is one of Agent, API Key, Document, Embedding Model, Embedding Provider, LLM, Pipeline, Search Indexer, Taxonomy, Text Splitter, Text Splitter Provider or Trace. details.id holds the identifier. |
Embedding Provider not found, Text Splitter Provider not found | An embedding model or text splitter create request names a provider that does not exist. details.provider holds the provider name. A provider on which the key lacks write permission returns HTTP 403 instead. |
Classification not found | A document names a classification that the pipeline does not define. A search with search_type 1 or 3 names a classification that the pipeline does not define. A classification outside the key's allow-list returns HTTP 403 instead. The response has no details. |
Pipeline Index not found | The metadata index does not exist. details.id holds the pipeline identifier and details.index_id the index identifier. |
Distance Index not found | A request to remove a distance index names a distance strategy that has no distance index. details.id holds the search index identifier and details.distance the strategy. |
Not found | The path does not exist, as described in Framework errors. |
A trace returns Trace not found after the 60-minute retention period, and also when a key other than the key that ran the execution requests the trace. The resolution for every 404 error is to check the identifier and the permissions of the key.
HTTP 409
| Message | Cause | Resolution |
|---|---|---|
Conflict unique error | The request would create a second object with a value that must be unique, such as a name already in use or an index that already exists. details.constraint names the database constraint, except for a metadata index that already exists, where the response has no details. | Choose another name, or update the existing object. |
Conflict related error | The request would delete an object that another object still references, such as an embedding model that a search index uses or a text splitter that a pipeline uses. details.constraint names the database constraint. | Change or delete the referencing objects first. |
Conflict | A search or a search index operation conflicts with the state of a search index, such as a search on an index that is still being built. details.error names the conflict, as listed in Search requests and in Search index operations. | Wait for the index, or change the request as details.error describes. |
Search index operations
The operations under /pipelines/{id}/search-indexers return the following errors in addition to the authentication, permission and not-found errors of every operation. details.error holds the message. Search indexes describes the operations.
| Status | details.error | Cause |
|---|---|---|
| 400 | Search indexer <id> is not a vector indexer | A distance index operation names a full-text or BM25 index. |
| 400 | The max-inner-product distance cannot be indexed | A distance index request names max-inner-product. |
| 400 | Search indexer <id> has no database indexes to rebuild | A rebuild names an index without database indexes. |
| 400 | A tokenizer message, such as Invalid Hugging Face repository '<repo>': expected 'owner/name' | The tokenizer of a BM25 index is invalid, or the tokenizer files could not be downloaded. |
| 409 | The pipeline already has a vchord indexer for embedding model <id>, The pipeline already has a pgvector indexer for embedding model <id> | The pipeline already has a vector index of that kind for the embedding model. |
| 409 | The pipeline already has a fts indexer | The pipeline already has a full-text index. |
| 409 | The pipeline already has a BM25 indexer with this tokenizer | The pipeline already has a BM25 index with the same tokenizer. |
| 409 | The pipeline is busy processing documents, try again shortly | Adding or deleting an index waited 10 seconds for document processing on the pipeline to pause. Repeat the request. |
| 409 | Search indexer <id> is a default of the pipeline: make another indexer the default first | A delete request names a default index. |
| 409 | Search indexer <id> is not ready and cannot be the pipeline's default | A default request names an index that is building or failed. |
| 409 | Search indexer <id> has not failed | A retry request names an index that is not failed. |
| 409 | Search indexer <id> already has an index for the <distance> distance | The distance index exists. |
| 409 | The indexes of search indexer <id> are already being built or rebuilt | A rebuild or a distance index build is running on the index. Repeat the request when the index's rebuild field is null. |
| 404 | Distance Index not found (message, not details.error) | A request to remove a distance index names a strategy without a distance index. details.id holds the search index identifier and details.distance the strategy. |
HTTP 500
| Message | Cause |
|---|---|
Internal server error | A component failed while processing the request: the database, the Redis-compatible cache, NATS JetStream, the gRPC service, an embedding model, language detection for full-text search, or the decryption of stored text or credentials. The response has no details. |
Internal error | The OpenAI-compatible endpoint could not build the response from the model server's reply. |
Failed to get message queue information | A statistics request could not read the state of NATS JetStream. |
The API server writes the cause of every Internal server error to the API server log at the error level, because the cause can contain database statements, hosts or file paths that a client must not receive. The API server also writes one log line for each request that fails: the message request failed at the warn level for a 5xx status, and the message request refused at the info level for a 4xx status. The line holds the method, the path without the query string (path), the status, the duration in milliseconds (elapsed_ms) and the x-request-id value (request_id). The prefix of the line, which names the HTTP request span, carries the query string as url.query. With the default log level warn, the log shows the lines of 5xx responses only. A 500 error that persists points to a component of the deployment. Operators find the cause in the API server log at the time of the request and, when OpenTelemetry export is enabled, the span of the request by the x-request-id value in the trace backend. The worker logs name the pipeline and document of a processing failure, as Observability describes.
HTTP 501
| Message | Cause |
|---|---|
F4ai enriched completions not implemented yet | A request to the OpenAI-compatible endpoint with all three of X-Agent-Id, X-Pipeline-Id and X-Pipeline-Classification. |
HTTP 502
| Message | Cause |
|---|---|
Upstream LLM error | The model server failed during an agent execution or an LLM query, as described in Errors during streamed responses. |
Upstream LLM request failed | The OpenAI-compatible endpoint could not reach the model server. The API server log records the reason. |
Failed reading upstream LLM response | The OpenAI-compatible endpoint could not read the reply of the model server. |
HTTP 503
| Message | Cause | Resolution |
|---|---|---|
Unable to validate the API key; try again later | The API server could not reach PostgreSQL or the Redis-compatible cache while checking the API key. The API server log records the cause. | Repeat the request later. When the error persists, check the database and cache connections of the API server. |
Provider unavailable | The gRPC service runs but lacks a Python package or model files that the request needs. details.error names what is missing. Creating an embedding model reports these causes with HTTP 500 Internal server error instead, as described in Embedding models and text splitters. | Provide the gRPC service with the package or the model files that details.error names. |
Prometheus could not be queried; see the server logs | A statistics request could not read any metric from Prometheus. | Check the Prometheus connection of the API server. |
Errors during streamed responses
Agent executions and LLM queries report a failure of the model server with the message Upstream LLM error, and the API server log records the reason. When the model server fails before the first part of the response, the request returns HTTP 502 with that message in the error body. A streamed response that has started has status 200, so a later failure cannot change the status, and the format of the response determines what the client observes:
stream | Client observation |
|---|---|
Omitted, true or "stream" (NDJSON) | The last line of the response is {"error":"Upstream LLM error"}. |
"sse" | The last event is an error event with the data {"error":"Upstream LLM error"}. |
false | HTTP 502 with the message Upstream LLM error. |
Response formats describes the three formats.
MCP errors
The MCP server under /mcp reports authentication failures with the HTTP 401 errors above. The MCP server keeps no session between requests, so no request fails because of an unknown or expired session. GET and DELETE requests on /mcp return HTTP 405 with the JSON error body Method not allowed and the header allow: POST. Other transport errors of the MCP server, such as a missing Accept type, a body without the JSON content type or a Host header that the server does not accept, return HTTP 400, 403, 406 or 415. Most of these responses have a plain-text body, and some HTTP 400 responses carry a JSON-RPC error object. A tool call whose arguments do not match the input schema returns a tool result with isError set to true. Other tool errors return JSON-RPC error objects with the message of the REST error: code -32002 for HTTP 404 errors such as Pipeline not found, -32602 for the other client errors, including HTTP 403, and for HTTP 501, and -32603 for server-side failures, with the REST message such as Internal server error or Provider unavailable. MCP tools lists the codes and messages.
Reporting a problem
A report of a failed request to the operator or to support includes the following information:
- Request. The method, the path and the time of the request.
- Response. The status code and the complete body.
x-request-id. The request identifier, which the API server records in the server's traces and in the log line of a failed request. A client can set the value in the request header of the same name.traceparent. The trace context header of the response, when present.x-foundation4ai-tracing-id. The trace identifier of an agent execution with tracing, which retrieves the retrieved fragments and the prompt for 60 minutes.