> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Flowker error list

> Flowker APIs return a structured error object for all errors to simplify issue diagnosis.

### Error format

<CodeGroup>
  ```json theme={null}
  {
     "code": "<error_code>",
     "title": "<error_title>",
     "message": "<error_message>"
  }
  ```
</CodeGroup>

### Field definitions

* **`code`** – A stable, unique identifier for the error. Useful for programmatic handling and support requests.
* **`title`** – A short, human-readable summary of the issue.
* **`message`** – Detailed guidance to help you resolve the error.

This structure ensures you always get actionable feedback when something doesn’t go as expected.

### Field-level error details

For issues specific to individual fields, a fields object provides additional context.

Examples:

<CodeGroup>
  ```json Example 1 theme={null}
  {
    "code": "FLK-0110",
    "title": "Missing Required Field",
    "message": "The name field is required. Please provide a name for the workflow and try again.",
    "fields": {
      "name": "name is a required field"
    }
  }
  ```

  ```json Example 2 theme={null}
  {
    "code": "FLK-0001",
    "title": "Invalid Request Body",
    "message": "The request body is invalid or malformed. Please verify the JSON format and try again.",
    "fields": {
      "nodes": "nodes field must contain at least one entry"
    }
  }
  ```
</CodeGroup>

## General errors

***

These errors apply to all Flowker API endpoints.

| Code     | Title                 | Message                                                                                        |
| -------- | --------------------- | ---------------------------------------------------------------------------------------------- |
| FLK-0001 | Invalid Request Body  | The request body is invalid or malformed. Please verify the JSON format and try again.         |
| FLK-0002 | Invalid ID            | The provided ID is not a valid UUID format. Please verify the ID and try again.                |
| FLK-9999 | Internal Server Error | An unexpected error occurred. Please try again later or contact support if the issue persists. |

## Request validation errors

***

These errors are returned when the API request does not meet validation requirements.

| Code     | Title                        | Message                                                                                                          |
| -------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| FLK-0300 | Unexpected Fields in Request | The request contains unexpected fields. Please remove the extra fields and try again.                            |
| FLK-0301 | Missing Fields in Request    | One or more required fields are missing. Please provide all required fields and try again.                       |
| FLK-0302 | Bad Request                  | The request is invalid. Please verify the request format and try again.                                          |
| FLK-0303 | Calculation Field Type Error | A field used in a calculation has an invalid type. Please verify the field types and try again.                  |
| FLK-0304 | Invalid Query Parameter      | One or more query parameters are invalid. Please verify the parameters and try again.                            |
| FLK-0305 | Invalid Date Format          | The date must be in RFC3339 format with timezone (e.g., 2026-01-28T10:30:00Z). Date-only format is not accepted. |
| FLK-0306 | Invalid Final Date           | The end date must be after the start date. Please provide a valid date range.                                    |
| FLK-0307 | Date Range Exceeds Limit     | The requested date range exceeds the maximum allowed period. Please reduce the date range.                       |
| FLK-0308 | Invalid Date Range           | The date range is invalid. Please verify the start and end dates.                                                |
| FLK-0309 | Pagination Limit Exceeded    | The limit parameter exceeds the maximum allowed value. Please reduce the limit and try again.                    |
| FLK-0310 | Invalid Sort Order           | Sort order must be ASC or DESC. Please provide a valid value.                                                    |
| FLK-0311 | Invalid Path Parameter       | The provided path parameter is invalid. Please verify the parameter value and try again.                         |
| FLK-0312 | Metadata Key Too Long        | The metadata key exceeds the maximum allowed length of 64 characters. Please reduce the key size.                |
| FLK-0313 | Metadata Value Too Long      | The metadata value exceeds the maximum allowed length. Please reduce the value size.                             |
| FLK-0314 | Invalid Metadata Nesting     | Metadata values cannot be nested objects. Please provide flat key-value pairs.                                   |
| FLK-0315 | Metadata Entries Exceeded    | The metadata exceeds the maximum number of entries. Please reduce the number of metadata entries.                |

## Entity errors

***

| Code     | Title                   | Message                                                                                            |
| -------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
| FLK-0400 | Entity Not Found        | The requested entity does not exist. Please verify the ID and try again.                           |
| FLK-0401 | Action Not Permitted    | This action is not permitted in the current state. Please check the resource status and try again. |
| FLK-0402 | Parent Entity Not Found | The referenced parent entity does not exist. Please verify the parent ID and try again.            |

## Workflow errors

***

| Code     | Title                           | Message                                                                                                                  |
| -------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| FLK-0100 | Workflow Not Found              | The requested workflow does not exist. Please verify the workflow ID and try again.                                      |
| FLK-0101 | Workflow Name Conflict          | A workflow with this name already exists. Please choose a different name and try again.                                  |
| FLK-0102 | Invalid Status Transition       | The requested status transition is not allowed. Please check the current workflow status and valid transitions.          |
| FLK-0103 | Workflow Cannot Be Modified     | Non-draft workflows cannot be modified. Please create a new version or revert to draft if supported.                     |
| FLK-0104 | Referenced Executor Not Found   | A node references an executor configuration that does not exist. Please verify the executor configuration ID.            |
| FLK-0105 | Invalid Conditional Expression  | The conditional expression is invalid or could not be evaluated. Please verify the expression syntax.                    |
| FLK-0110 | Workflow Name Required          | The name field is required. Please provide a name for the workflow and try again.                                        |
| FLK-0111 | Workflow Name Too Long          | The workflow name exceeds the maximum allowed length. Please reduce the name size.                                       |
| FLK-0112 | Workflow Nodes Required         | A workflow must have at least one node. Please add nodes to the workflow and try again.                                  |
| FLK-0113 | Too Many Nodes                  | The workflow exceeds the maximum number of nodes allowed. Please reduce the node count.                                  |
| FLK-0114 | Too Many Edges                  | The workflow exceeds the maximum number of edges allowed. Please reduce the edge count.                                  |
| FLK-0115 | Invalid Edge Reference          | An edge references a node that does not exist in the workflow. Please verify all edge source and target values.          |
| FLK-0116 | Missing Trigger Node            | The workflow must have at least one trigger node. Please add a trigger and try again.                                    |
| FLK-0120 | Node ID Required                | Each node must have an ID. Please provide an ID for all nodes.                                                           |
| FLK-0121 | Node Type Required              | Each node must have a type. Please provide a type for all nodes.                                                         |
| FLK-0130 | Edge ID Required                | Each edge must have an ID. Please provide an ID for all edges.                                                           |
| FLK-0131 | Edge Source Required            | Each edge must specify a source node. Please provide the source node ID.                                                 |
| FLK-0132 | Edge Target Required            | Each edge must specify a target node. Please provide the target node ID.                                                 |
| FLK-0140 | Invalid Input Mapping           | The input mapping configuration is invalid. Please verify the mapping syntax and field references.                       |
| FLK-0141 | Invalid Output Mapping          | The output mapping configuration is invalid. Please verify the mapping syntax and field references.                      |
| FLK-0142 | Invalid Transforms              | The transformation configuration is invalid. Please verify the transform expressions.                                    |
| FLK-0150 | Invalid Provider Configuration  | The provider configuration specified in the node is invalid. Please verify the configuration format.                     |
| FLK-0151 | Provider Configuration Mismatch | The provider configuration does not match the expected schema for this provider. Please verify the configuration fields. |

## Catalog, executor, and trigger errors

***

| Code     | Title                            | Message                                                                                                    |
| -------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| FLK-0200 | Executor Not Found               | The requested executor does not exist in the catalog. Please verify the executor ID and try again.         |
| FLK-0201 | Invalid Executor Configuration   | The executor configuration is invalid. Please verify the configuration format.                             |
| FLK-0210 | Trigger Not Found                | The requested trigger does not exist in the catalog. Please verify the trigger ID and try again.           |
| FLK-0211 | Invalid Trigger Configuration    | The trigger configuration is invalid. Please verify the configuration format.                              |
| FLK-0220 | Runner Not Found                 | The requested runner does not exist. Please verify the runner ID and try again.                            |
| FLK-0230 | Provider Not Found               | The requested provider does not exist in the catalog. Please verify the provider ID and try again.         |
| FLK-0231 | Provider Duplicate               | A provider with this identifier already exists. Please use the existing provider or choose a different ID. |
| FLK-0232 | Invalid Provider Configuration   | The provider configuration is invalid. Please verify the configuration format.                             |
| FLK-0233 | Provider Executor Not Configured | The provider executor is not configured. Please configure the executor before proceeding.                  |

## Executor configuration errors

***

| Code     | Title                                     | Message                                                                                                     |
| -------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| FLK-0250 | Executor Configuration Not Found          | The requested executor configuration does not exist. Please verify the ID and try again.                    |
| FLK-0251 | Executor Configuration Name Conflict      | An executor configuration with this name already exists. Please choose a different name and try again.      |
| FLK-0252 | Executor Configuration Cannot Be Modified | The executor configuration cannot be modified in its current status. Please check the status and try again. |
| FLK-0260 | Executor Configuration Name Required      | The name field is required. Please provide a name for the executor configuration.                           |
| FLK-0261 | Executor Configuration Name Too Long      | The executor configuration name exceeds the maximum allowed length. Please reduce the name size.            |
| FLK-0262 | Base URL Required                         | The baseUrl field is required. Please provide a base URL for the executor configuration.                    |
| FLK-0263 | Invalid Base URL                          | The provided base URL is not a valid URL. Please verify the URL format.                                     |
| FLK-0264 | Base URL Too Long                         | The base URL exceeds the maximum allowed length. Please reduce the URL size.                                |
| FLK-0265 | Endpoints Required                        | At least one endpoint must be configured. Please provide endpoint definitions.                              |
| FLK-0266 | Auth Configuration Required               | Authentication configuration is required. Please provide auth settings.                                     |
| FLK-0267 | Description Too Long                      | The description exceeds the maximum allowed length. Please reduce the description size.                     |
| FLK-0268 | Auth Type Required                        | The auth type field is required. Please provide an authentication type.                                     |
| FLK-0269 | Invalid Auth Type                         | The auth type is not recognized. Please provide a valid authentication type.                                |
| FLK-0270 | Endpoint Name Required                    | Each endpoint must have a name. Please provide names for all endpoints.                                     |
| FLK-0271 | Endpoint Path Required                    | Each endpoint must have a path. Please provide paths for all endpoints.                                     |
| FLK-0272 | Endpoint Method Required                  | Each endpoint must specify an HTTP method. Please provide methods for all endpoints.                        |
| FLK-0273 | Invalid Endpoint Method                   | The HTTP method is not valid. Please use one of GET, POST, PUT, PATCH, or DELETE.                           |
| FLK-0280 | Connectivity Test Failed                  | The connectivity test to the external service failed. Please verify the base URL and credentials.           |
| FLK-0281 | Endpoint Unreachable                      | The configured endpoint could not be reached. Please verify the URL and network connectivity.               |
| FLK-0282 | Auth Test Failed                          | Authentication with the external service failed. Please verify the credentials and auth configuration.      |
| FLK-0283 | Transform Test Failed                     | The data transformation test failed. Please verify the transformation expressions.                          |

## Provider configuration errors

***

| Code     | Title                                     | Message                                                                                                           |
| -------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| FLK-0290 | Provider Configuration Not Found          | The requested provider configuration does not exist. Please verify the ID and try again.                          |
| FLK-0291 | Provider Configuration Name Conflict      | A provider configuration with this name already exists. Please choose a different name and try again.             |
| FLK-0292 | Provider Configuration Cannot Be Modified | The provider configuration cannot be modified in its current status. Please check the status and try again.       |
| FLK-0293 | Invalid Provider Configuration Schema     | The provider configuration does not match the provider's required schema. Please verify the configuration fields. |
| FLK-0294 | Provider Not Found in Catalog             | The referenced provider does not exist in the catalog. Please verify the provider ID.                             |
| FLK-0295 | Provider Configuration Name Required      | The name field is required. Please provide a name for the provider configuration.                                 |
| FLK-0296 | Provider Configuration Name Too Long      | The provider configuration name exceeds the maximum allowed length. Please reduce the name size.                  |
| FLK-0297 | Provider ID Required                      | The providerId field is required. Please provide a provider ID.                                                   |
| FLK-0298 | Configuration Object Required             | The config field is required. Please provide the provider configuration object.                                   |
| FLK-0299 | Description Too Long                      | The description exceeds the maximum allowed length. Please reduce the description size.                           |
| FLK-0340 | Missing Base URL                          | The provider configuration is missing the required base\_url field. Please add the base URL to the configuration. |

## Workflow execution errors

***

| Code     | Title                    | Message                                                                                                                  |
| -------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| FLK-0500 | Execution Not Found      | The requested execution does not exist. Please verify the execution ID and try again.                                    |
| FLK-0501 | Workflow Not Active      | The workflow is not in an active state and cannot be executed. Please activate the workflow and try again.               |
| FLK-0502 | Execution In Progress    | A previous execution for this workflow is still in progress. Please wait for it to complete.                             |
| FLK-0503 | Execution Timeout        | The workflow execution timed out before completing. Please check the workflow logic and external service response times. |
| FLK-0504 | Execution Node Failed    | A node within the workflow failed during execution. Please check the execution details for the specific node error.      |
| FLK-0505 | Duplicate Execution      | An execution with this idempotency key already exists. Please use a new key for distinct executions.                     |
| FLK-0506 | Input Payload Too Large  | The request body must not exceed 1 MB. Please reduce the input payload size.                                             |
| FLK-0507 | Circuit Breaker Open     | The circuit breaker for this executor is open due to repeated failures. Please wait before retrying.                     |
| FLK-0508 | Execution Cycle Detected | A cycle was detected in the workflow graph. Please review the edges and remove circular references.                      |
| FLK-0509 | Missing Idempotency Key  | The Idempotency-Key header is required for execution requests. Please include a unique key in the header.                |

## Fault injection errors (test environments only)

***

These errors are only returned in environments with fault injection enabled. They are not present in production.

| Code     | Title               | Message                                                |
| -------- | ------------------- | ------------------------------------------------------ |
| FLK-0800 | Gateway Timeout     | Simulated gateway timeout for testing purposes.        |
| FLK-0801 | Service Unavailable | Simulated service unavailability for testing purposes. |