Errors

All errors from the MCP Server tool calls follow this consistent JSON structure:

{
  "error": {
    "name": "FlorentineApiError",
    "statusCode": 500,
    "message": "The provided Florentine API key is invalid. You can find the key in your account settings: https://florentine.ai/settings",
    "errorCode": "INVALID_TOKEN",
    "requestId": "abc123"
  }
}

Field	Type	Description
name	string	Error class name (e.g. FlorentineApiError, FlorentineConnectionError)
statusCode	number	HTTP status code (e.g. 400, 500)
message	string	Explanation of what went wrong
errorCode	string	Error identifier (e.g. NO_TOKEN, INVALID_LLM_KEY)
requestId	string	Unique ID for this request (helpful for support and debugging)

Custom client error handling

The error object is returned as a stringified json in the content array:

{
  "content": [
    {
      "type": "text",
      "text": "{\"error\":{\"name\":\"FlorentineApiError\",\"statusCode\":401,\"message\":\"The provided Florentine API key is invalid. You can find the key in your account settings: https://florentine.ai/settings\",\"errorCode\":\"INVALID_TOKEN\",\"requestId\":\"uhv99g\"}}"
    }
  ],
  "isError": true
}

You may parse the JSON in text and handle the different errors inside your custom client/agent.

Common errors

Error Name	errorCode	Meaning
FlorentineApiError	INVALID_TOKEN	The Florentine API key is invalid
FlorentineApiError	LLM_KEY_WITHOUT_SERVICE	You must provide a llmService if llmKey is defined
FlorentineApiError	LLM_SERVICE_WITHOUT_KEY	You must provide a llmKey if llmService is defined
FlorentineApiError	INVALID_LLM_SERVICE	Invalid llmService provided
FlorentineApiError	NO_OWN_LLM_KEY	You need to provide your own llm key
FlorentineApiError	NO_ACTIVE_COLLECTIONS	No collections activated for the account
FlorentineApiError	MISSING_REQUIRED_INPUT	Required input is missing
FlorentineApiError	INVALID_REQUIRED_INPUT	Required input is invalid
FlorentineApiError	INVALID_REQUIRED_INPUT_FORMAT	Required input format is invalid
FlorentineApiError	NO_QUESTION	Question is missing
FlorentineApiError	EXECUTION_FAILURE	Created aggregation execution failed
FlorentineApiError	NO_CHAT_ID	History chat id required but missing
FlorentineApiError	TOO_MANY_TOKENS	The aggregation prompt exceeds the maximum tokens of the LLM model
FlorentineLLMError	API_KEY_ISSUE	LLM API key is invalid
FlorentineLLMError	NO_RETURN	Florentine.ai did not receive a valid LLM return
FlorentineLLMError	RATE_LIMIT_EXCEEDED	LLM Request size too big
FlorentineConnectionError	CONNECTION_REFUSED	Could not connect to database for aggregation execution
FlorentineCollectionError	NO_EXECUTION	Created aggregation could not be executed
FlorentinePipelineError	MODIFICATION_FAILED	Modifying the aggregation pipeline failed
FlorentineUsageError	LIMIT_REACHED	All API requests included in your plan depleted
FlorentineUnknownError	UNKNOWN_ERROR	All occurring unknown errors