Errors

This page lists the errors that the Foundation4 REST API returns: the error body, the responses that do not use the error body, 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 of details depends 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.

Responses without the error body

The following responses come from the web framework or from other servers, and do not use the JSON error body:

Status	Body	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 as missing, as 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, or a required query parameter is missing.
404	Empty	The path does not exist. The response carries no x-request-id header.
405	Empty	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 2 megabytes.
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 or an enumerated field has an unknown value. 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 query: invalid type: integer `5`, expected a string at line 1 column 11. A missing field has no path prefix, as in missing field `query` at line 1 column 98.
Any	The model server's body	The OpenAI-compatible endpoint returns the status and body of an error response from the model server unchanged.

Apart from the empty responses and the model server's body, these responses have a plain-text body. 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.	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, or carries a cursor that cannot be read.	Use one pagination mode 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 or search.
Vector embedding not found	A search names an embedding model that the pipeline does not use, or the pipeline has no embedding model. details.embedding_id holds the requested identifier.	Omit params.embedding, or name the pipeline's embedding model.
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.	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.	Define every placeholder that a template names, and set each target to a query placeholder.
Invalid placeholder of type <placeholder>	An agent placeholder has an invalid value, such as k of 0, fetch_k less than k or lambda_mult outside 0 to 1.	Correct the placeholder parameters.
Invalid object type	A permissions request names an object type that does not exist.	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.

Invalid parameter details

details.error of an Invalid parameter error holds a message such as the following:

details.error	Cause
Unknown provider type: <provider>	An embedding model or text splitter request names a provider that does not exist.
Embedding provider '<provider>' or model '<model>' not found with the provided parameters	The gRPC service does not recognize the model or the parameters of an embedding model.
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.
Text splitter provider '<provider>' not found or invalid parameters provided	The gRPC service does not recognize the text splitter or the parameters.
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: <reason>	The gRPC service could not load the embedding model, for example because the deployment cannot download the model files.
<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.
API key is required for OpenAI provider	An agent execution or LLM query uses an LLM registration without an API key.
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.

HTTP 401

Message	Cause	Resolution
Unauthorized: No API Key specified.	The x-api-key header is missing, or the header value contains characters other than visible ASCII characters.	Send both authentication headers, and copy the key identifier as plain text.
Unauthorized: No API Secret Key specified.	The x-api-key-secret header is missing, or the header value contains characters other than visible ASCII characters.	Send both authentication headers, and 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. The same message appears when the API server cannot reach the database while checking the key.	Check the key and the secret. When a correct key fails for every client, check the database connection of the API server.

Authenticate describes the authentication headers.

HTTP 403

Message	Cause	Resolution
Unauthorized: access level <level> required for <type> with id <id>	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.
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 any object type exceeds the limit for that type, every create and change that checks the license fails, whatever the object type.	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 access level message, <level> has the form AccessLevel(READ), AccessLevel(WRITE) or AccessLevel(EXECUTE), or a combination such as AccessLevel(READ | EXECUTE). <id> has the form Some(<uuid>) for an object and None for an object type. The following message reports a missing write permission on one pipeline:

Unauthorized: access level AccessLevel(WRITE) required for Pipeline with id Some(3f0c9b6e-2d4a-4c1e-9b7f-5a8d2e6c1f04)

The message does not state the reason for the refusal. The following causes return the same 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 the classification of a document that the operation creates, expires or deletes. Operations on all documents of a pipeline require an allow-list that covers every classification of the pipeline.
• Pipeline classifications. GET and POST /pipelines/{id}/classifications require the * allow-list. Without that allow-list, the message names AccessLevel(READ) or AccessLevel(WRITE) even when the key holds the permission.
• Key management. A key cannot grant a permission that the key does not hold itself, and cannot delete itself.

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 return HTTP 403 when the document's pipeline exists and the key lacks the permission. Listing documents and reading fragments return HTTP 404.

HTTP 404

Message	Cause
<type> with id <id> 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, Fragment, Embedding Model, Embedding Provider, LLM, Pipeline, Pipeline Index, Taxonomy, Text Splitter, Text Splitter Provider, Trace or Classification.
Pipeline not found	The pipeline does not exist, or the key lacks the permission on the pipeline that the operation requires. details.id holds the identifier on most operations.
Agent not found, Document not found, LLM not found, Taxonomy not found, Embedding model not found, ApiKey not found	The object does not exist, or the key cannot read the object. details.id holds the identifier. The agent retrieval dry run returns Agent not found without details.
Embedding provider not found, Text Splitter provider not found	The provider requested by identifier does not exist, or the key cannot read the provider.
Embedding Provider not found	An embedding model create request names a provider on which the key lacks write permission. A provider name that does not exist returns HTTP 400 Invalid parameter instead.
Text Splitter not found	The text splitter does not exist, or the key lacks the permission on the text splitter. A text splitter create request that names a provider on which the key lacks write permission returns the same message. A provider name that does not exist returns HTTP 400 Invalid parameter instead.
Classification not found	A document names a classification that the pipeline does not define, or a classification outside the key's allow-list. A search with search_type 1 or 3 names a classification that the pipeline does not define.
Pipeline Index not found	The metadata index does not exist.

A trace returns Trace with id <id> 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.	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 or a text splitter that a pipeline uses.	Change or delete the referencing objects first.

HTTP 500

Message	Cause
Internal error	A component failed while processing the request. details.error holds the cause, as listed below.
Stream error: <reason>	The model server failed during an agent execution or an LLM query with "stream": false.
Decryption error	Stored text or credentials could not be decrypted or read, for example a stored agent trace after the application secret of the deployment changed.
Database connection error: <reason>	The API server could not start a database transaction.
A database error message	The database rejected a query, for example a filter on a nested metadata field.
A gRPC error message, such as code: 'The service is currently unavailable'	The gRPC service that runs embedding models and text splitters is unreachable or failed.
NATS error	The API server could not reach NATS JetStream.
An HTTP client error message	The OpenAI-compatible endpoint could not reach the model server.

details.error of an Internal error holds one of the following messages:

details.error	Cause
Failed computing embeddings: <reason>	The embedding model failed to convert text into vectors.
gRPC error: <status>	The gRPC service failed while splitting text.
Received empty embedding vector	The embedding model returned no vector, or the text splitter returned no fragments.
Failed to detect language: <reason>	Language detection for full-text search failed.
Datastore error: <reason>	Retrieval failed during an agent execution or an agent retrieval dry run, for example because of a filter error.

A 500 error that persists points to a component of the deployment. When OpenTelemetry export is enabled, operators find the span of the request by the x-request-id value in the trace backend. The API server writes no log line for a failed request, and the worker logs name the pipeline and document of a processing failure, as Observability describes.

HTTP 501

Message	Cause
Full text search is not enabled for this pipeline	A full-text search on a pipeline created without full-text search. details.params holds the parsed search parameters.
Hybrid placeholder is not implemented yet	A search with type set to hybrid.
History placeholder is not implemented yet	A search with type set to history.
Not implemented	An agent create or update request with a hybrid or history placeholder.
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.

Errors during streamed responses

Agent executions and LLM queries return status 200 as soon as a streamed response starts, so a failure of the model server during generation cannot change the status. The format of the response determines what the client observes:

stream	Client observation
Omitted, true or "stream" (NDJSON)	The response ends early or is empty, with no error object.
"sse"	The connection closes before the response is complete.
false	HTTP 500 with the message Stream error: <reason>, and no x-foundation4ai-tracing-id header.

A client application that needs the error message of the model server repeats the request with "stream": false. Response formats describes the three formats.

MCP errors

The MCP server under /mcp reports authentication failures with the HTTP 401 errors above. Transport errors of the MCP server, such as a missing Accept type or an unknown session, return HTTP 400, 403, 404, 405, 406, 413, 415 or 422 with a plain-text body. A tool call whose arguments do not match the input schema returns a tool result with isError set to true, and other tool errors return JSON-RPC error objects. 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. 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.