Flowker error list

Error format

The /v1 management API returns errors as an RFC 9457 problem document, served with the application/problem+json content type. Webhook routes answer in their trigger’s configured format. See Errors on webhook routes.

{
  "type": "https://errors.lerian.studio/v1/FLK-0110",
  "title": "Bad Request",
  "status": 400,
  "detail": "name is a required field",
  "instance": "/v1/workflows",
  "code": "FLK-0110"
}

Field definitions

code – The stable Flowker error code. Branch your integration on this field.
type – A URI that identifies the error. It is always https://errors.lerian.studio/v1/ plus the code.
title – The standard HTTP reason phrase for status, such as Not Found or Conflict. It does not change per error code.
status – The HTTP status code, repeated in the body.
detail – A human-readable explanation of this occurrence. Responses with a status of 500 or above carry a fixed generic message instead, so use code to tell them apart.
instance – A URI that identifies this specific occurrence, when the endpoint provides one.
errors – An optional array of per-field entries. See Field-level error details.

Field-level error details

When a request fails validation on specific fields, the problem document carries an errors array. Each entry names the offending input.

{
  "type": "https://errors.lerian.studio/v1/FLK-0301",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "code": "FLK-0301",
  "errors": [
    {
      "location": "body.name",
      "message": "expected required property name to be present"
    }
  ]
}

{
  "type": "https://errors.lerian.studio/v1/FLK-0001",
  "title": "Bad Request",
  "status": 400,
  "detail": "request body is invalid or malformed",
  "code": "FLK-0001",
  "errors": [
    {
      "location": "body.nodes",
      "message": "expected array length >= 1",
      "value": []
    }
  ]
}

Each entry carries a location (where the problem is, such as body.nodes or path.id), a message, and the offending value when it is safe to echo.

Errors on webhook routes

A webhook route answers in its trigger’s configured format. A JSON webhook route returns a compact error object with the application/json content type:

{
  "code": "FLK-0361",
  "title": "Not Found",
  "message": "no webhook registered for this path and method"
}

code – The stable Flowker error code, taken from the tables below. Branch your integration on this field.
title – The HTTP reason phrase for the response status, such as Not Found or Payload Too Large.
message – A human-readable explanation of this occurrence.

An XML webhook route returns an <error> document instead, because the whole route works in XML.

<error>
  <code>XML_VALIDATION_FAILED</code>
  <message>element 'valor' is not a valid decimal</message>
  <details>line 12, column 5</details>
  <requestId>018f3e2a-1c4d-7b9e-a1b2-c3d4e5f6a7b8</requestId>
</error>

The code element carries either a Flowker code from the tables below or one of two XML-specific codes:

Code	What it means
`XML_MALFORMED`	The request body is not well-formed XML. Returned with HTTP 400.
`XML_VALIDATION_FAILED`	The body is well-formed XML but does not conform to the route’s XSD. Returned with HTTP 422, and `details` carries the line and column of the first finding.

General errors

These errors apply to all Flowker API endpoints.

Code	What it means
FLK-0001	The request body is invalid or malformed. Verify the JSON format and try again.
FLK-0002	The provided ID is not a valid UUID. Verify the ID and try again.
FLK-0003	Authentication is required to access this resource. Send a valid bearer token.
FLK-0004	You do not have permission to perform this action. Check the permissions granted to your token.
FLK-9999	An unexpected error occurred. Try again later, or contact support if the issue persists.

Request validation errors

The API returns these errors when the request does not meet validation requirements.

Code	What it means
FLK-0300	The request contains unexpected fields. Remove the extra fields and try again.
FLK-0301	One or more required fields are missing. Provide all required fields and try again.
FLK-0302	The request is invalid. Verify the request format and try again.
FLK-0303	A field used in a calculation has an invalid type. Verify the field types and try again.
FLK-0304	One or more query parameters are invalid. Verify the parameters and try again.
FLK-0305	The date must be in RFC 3339 format with a timezone, such as `2026-01-28T10:30:00Z`. Date-only values are rejected.
FLK-0306	The end date must be after the start date. Provide a valid date range.
FLK-0307	The requested date range exceeds the maximum allowed period. Reduce the date range.
FLK-0308	The date range is invalid. Verify the start and end dates.
FLK-0309	The `limit` parameter exceeds the maximum allowed value. Reduce the limit and try again.
FLK-0310	Sort order must be `ASC` or `DESC`. Provide a valid value.
FLK-0311	The provided path parameter is invalid. Verify the parameter value and try again.
FLK-0312	The metadata key exceeds the maximum allowed length of 64 characters. Reduce the key size.
FLK-0313	The metadata value exceeds the maximum allowed length. Reduce the value size.
FLK-0314	Metadata values cannot be nested objects. Provide flat key-value pairs.
FLK-0315	The metadata exceeds the maximum number of entries. Reduce the number of metadata entries.
FLK-0321	The pagination cursor is malformed or could not be decoded. Request the first page again and follow the cursor returned by the API.

Entity errors

Code	What it means
FLK-0400	The requested entity does not exist. Verify the ID and try again.
FLK-0401	This action is not permitted in the current state. Check the resource status and try again.
FLK-0402	The referenced parent entity does not exist. Verify the parent ID and try again.

Workflow errors

Code	What it means
FLK-0100	The requested workflow does not exist. Verify the workflow ID and try again.
FLK-0101	A workflow with this name already exists. Choose a different name and try again.
FLK-0102	The requested status transition is not allowed. Check the current workflow status and the valid transitions.
FLK-0103	Non-draft workflows cannot be modified. Create a new version, or revert the workflow to draft.
FLK-0104	A node references a catalog executor that does not exist. Verify the `executorId` on the node.
FLK-0105	The conditional expression is invalid or could not be evaluated. Verify the expression syntax.
FLK-0110	The `name` field is required. Provide a name for the workflow and try again.
FLK-0111	The workflow name exceeds the maximum allowed length. Reduce the name size.
FLK-0112	A workflow must have at least one node. Add nodes to the workflow and try again.
FLK-0113	The workflow exceeds the maximum number of nodes allowed. Reduce the node count.
FLK-0114	The workflow exceeds the maximum number of edges allowed. Reduce the edge count.
FLK-0115	An edge references a node that does not exist in the workflow. Verify all edge source and target values.
FLK-0116	The workflow must have at least one trigger node. Add a trigger and try again.
FLK-0117	The schedule trigger carries an invalid cron expression. Use a standard 5-field cron. Sub-minute schedules are not supported.
FLK-0118	The workflow has no schedule trigger, so it has no upcoming occurrences to list or manage.
FLK-0120	Each node must have an ID. Provide an ID for all nodes.
FLK-0121	Each node must have a type. Provide a type for all nodes.
FLK-0122	An action node’s `set_output` `responseStatusCode` override must be an integer between 200 and 599. Correct the value and try again.
FLK-0130	Each edge must have an ID. Provide an ID for all edges.
FLK-0131	Each edge must specify a source node. Provide the source node ID.
FLK-0132	Each edge must specify a target node. Provide the target node ID.
FLK-0140	The input mapping configuration is invalid. Verify the mapping syntax and field references.
FLK-0141	The output mapping configuration is invalid. Verify the mapping syntax and field references.
FLK-0142	The transformation configuration is invalid. Verify the transform expressions.
FLK-0143	A node’s `data.body` template could not be resolved against the workflow context, because a `${...}` reference is malformed or does not resolve. The node fails without calling the external service.
FLK-0150	The node’s `providerConfigId` is missing, is not a valid UUID, or names a provider configuration that does not exist or is not active. Verify the `providerConfigId` on every executor node, and the existence and status of the configuration it names.
FLK-0151	A node pairs a provider configuration of one provider with an executor of another. Verify that the `providerId` on the configuration and the `executorId` on the node name the same catalog provider.

Workflow condition errors

The API returns these errors when a node’s structured condition object fails validation during workflow creation or update.

Code	What it means
FLK-0160	The condition’s `version` field is missing or is not `2`.
FLK-0161	The condition object is structurally malformed, such as a `cases` value that is not an array.
FLK-0162	The condition has no cases. Add at least one case.
FLK-0163	Two cases, or a case and the default branch, share the same output handle ID. Give each branch a unique handle.
FLK-0164	A case has an empty output handle ID. Provide a handle for every case.
FLK-0165	The condition `mode` must be `rules` or `value`.
FLK-0166	A `value` mode condition needs a subject operand. Provide the subject.
FLK-0167	A group’s `combinator` must be `and` or `or`.
FLK-0168	A group carries neither rules nor nested groups. Add at least one rule, or remove the group.
FLK-0169	The rule operator is not recognized. Use an operator from the supported taxonomy.
FLK-0170	The rule `valueType` is not recognized. Use a value type from the supported taxonomy.
FLK-0171	The operator is not allowed for the selected `valueType`. Change the operator or the value type.
FLK-0172	An operand has an empty `source` path. Provide the path to read.
FLK-0173	A transform has an invalid operation, or invalid parameters for its operation.
FLK-0174	A right operand’s `kind` must be `literal` or `source`, and a `source` right operand needs a source path.
FLK-0175	The default branch has an empty output handle ID. Provide a handle.
FLK-0176	The condition exceeds the maximum number of cases. Reduce the number of cases.
FLK-0177	A group exceeds the maximum number of rules. Split the rules across nested groups.
FLK-0178	An operand’s transform pipeline exceeds the maximum number of transforms. Reduce the pipeline.
FLK-0179	A `matchesRegex` or `notMatchesRegex` rule carries a regular expression that exceeds the maximum length.
FLK-0180	An `isIn` or `notIn` rule carries a list that exceeds the maximum number of items.
FLK-0181	The condition is structurally valid but could not be compiled. Review the operands and literals on the reported node.
FLK-0182	The condition tree is too large across all its cases. Reduce the number of groups and rules.

Catalog, executor, and trigger errors

Code	What it means
FLK-0200	The requested executor does not exist in the catalog. Verify the executor ID and try again.
FLK-0201	A node’s configuration does not match the catalog executor’s JSON Schema. Verify it against that schema.
FLK-0210	The requested trigger does not exist in the catalog. Verify the trigger ID and try again.
FLK-0211	The trigger configuration is invalid. Verify the configuration format.
FLK-0220	The requested runner does not exist. Verify the runner ID and try again.
FLK-0230	The requested provider does not exist in the catalog. Verify the provider ID and try again.
FLK-0231	A provider with this identifier already exists. Use the existing provider, or choose a different ID.
FLK-0232	The provider configuration is invalid. Verify the configuration format.
FLK-0240	The requested template does not exist in the catalog. Verify the template ID and try again.
FLK-0242	One or more template parameters are invalid. Verify the parameters against the template schema.

Executor configuration errors

Code	What it means
FLK-0250	The requested executor configuration does not exist. Verify the ID and try again.
FLK-0251	An executor configuration with this name already exists. Choose a different name and try again.
FLK-0252	The executor configuration cannot be modified in its current status. Check the status and try again.
FLK-0260	The `name` field is required. Provide a name for the executor configuration.
FLK-0261	The executor configuration name exceeds the maximum allowed length. Reduce the name size.
FLK-0262	The `baseUrl` field is required. Provide a base URL for the executor configuration.
FLK-0263	The provided base URL is not a valid URL. Verify the URL format.
FLK-0264	The base URL exceeds the maximum allowed length. Reduce the URL size.
FLK-0265	At least one endpoint must be configured. Provide endpoint definitions.
FLK-0266	Authentication configuration is required. Provide auth settings.
FLK-0267	The description exceeds the maximum allowed length. Reduce the description size.
FLK-0268	The auth type field is required. Provide an authentication type.
FLK-0269	The auth type is not recognized. Provide a valid authentication type.
FLK-0270	Each endpoint must have a name. Provide names for all endpoints.
FLK-0271	Each endpoint must have a path. Provide paths for all endpoints.
FLK-0272	Each endpoint must specify an HTTP method. Provide methods for all endpoints.
FLK-0273	An endpoint’s HTTP method is not recognized. Verify the method on every endpoint and try again.
FLK-0284	The base URL resolves to an address Flowker refuses to call, such as a loopback or link-local host. Use a routable external host.
FLK-0285	The base URL host is not permitted by the configuration’s allowed-hosts list. Add the host to the list, or change the URL.

Provider configuration errors

Code	What it means
FLK-0290	The requested provider configuration does not exist. Verify the ID and try again.
FLK-0291	A provider configuration with this name already exists. Choose a different name and try again.
FLK-0292	The provider configuration cannot be modified in its current status. Check the status and try again.
FLK-0293	The `config` object does not match the provider’s required schema, or a `schemaBindings` entry is malformed — an unknown `type`, a `schemaId` that is empty, is not a UUID, or is all zeros, `operations` on a binding that is not `openapi`, or an operation whose path or HTTP method is missing or invalid. Verify the configuration fields and each schema binding.
FLK-0294	The referenced provider does not exist in the catalog. Verify the provider ID.
FLK-0295	The `name` field is required. Provide a name for the provider configuration.
FLK-0296	The provider configuration name exceeds the maximum allowed length. Reduce the name size.
FLK-0297	The `providerId` field is required for a `catalog` provider configuration. Provide a provider ID.
FLK-0298	The `config` field is required. Provide the provider configuration object.
FLK-0299	The description exceeds the maximum allowed length. Reduce the description size.
FLK-0316	The provider configuration ID is required for this operation. Provide the ID.
FLK-0317	An entry in the allowed-hosts list is not a valid host. Verify each entry.
FLK-0320	A base URL in the configuration points at a host its own allowed-hosts list rejects. Align the URL and the list.
FLK-0323	A configuration for the generic HTTP provider must declare an allowed-hosts list. An empty list would allow calls to any address, so it is rejected.
FLK-0952	The update changed the auth type without supplying a credential the new type requires and the previous one did not. Send that value with the type change.
FLK-0953	The request sent a masked credential placeholder. Omit the field to keep the stored credential, or send its actual value to replace it.

External OpenAPI provider configuration errors

These errors apply to provider configurations of kind external_openapi, which call an operation declared by a stored OpenAPI schema.

Code	What it means
FLK-0946	The configuration omits the required `config.openapi_schema_id` reference. Provide the schema ID.
FLK-0947	The referenced OpenAPI schema does not exist in your tenant. Verify the schema ID.
FLK-0948	The `config.auth` block is malformed — an unknown type, a missing required field, or the wrong shape.
FLK-0949	Neither `config.base_url` nor a usable `servers` entry in the referenced schema resolves a base URL. The node fails without calling the service.
FLK-0950	The bound operation is absent from the referenced schema, or the stored schema no longer parses. The node fails without calling the service.
FLK-0951	The HMAC request-signing scheme could not resolve its secret. The request is never sent unsigned.

Provider schema binding errors

Code	What it means
FLK-0942	A schema binding references an XSD or OpenAPI schema ID that does not exist in your tenant. Verify the schema ID.
FLK-0943	An OpenAPI schema binding restricts to an operation that the referenced document does not declare. Verify the path and method.
FLK-0944	The configuration lists the same binding twice. Remove the duplicate.
FLK-0945	The schema cannot be deleted because at least one active provider configuration binds it. The response lists the referring provider configurations and workflows.

Workflow execution errors

Code	What it means
FLK-0500	The requested execution does not exist. Verify the execution ID and try again.
FLK-0501	The workflow is not in an active state and cannot be executed. Activate the workflow and try again.
FLK-0502	A previous execution for this workflow is still in progress. Wait for it to complete.
FLK-0503	The workflow execution timed out before completing. Check the workflow logic and the response times of external services.
FLK-0504	A node within the workflow failed during execution. Check the execution details for the specific node error.
FLK-0505	An execution with this idempotency key already exists. Use a new key for distinct executions.
FLK-0506	The request body must not exceed 1 MB. Reduce the input payload size.
FLK-0507	The circuit breaker for this provider configuration is open after repeated failures. Wait before retrying.
FLK-0508	A cycle was detected in the workflow graph. Review the edges and remove the circular references.
FLK-0509	The `Idempotency-Key` header is required for execution requests. Include a unique key in the header.

Outbound request errors

These errors occur while a node calls an external service. They surface as node failures in the execution details.

Code	What it means
FLK-0322	The provider’s response body exceeds the configured size cap. Retrying does not help — the response will not shrink.
FLK-0324	The request body Flowker would send exceeds the configured size cap. The request is rejected before any network call.
FLK-0937	An HTTP node declares `request_format` of type `xml_converted` without a valid `root_element`. Provide a syntactically valid XML element name.
FLK-0938	An `xml_passthrough` node has no XML trigger payload to forward. Passthrough forwards the trigger’s original bytes, so it needs an XML trigger.
FLK-0939	An `xml_passthrough` node’s retained trigger payload is not eligible for byte-exact forwarding, such as a payload that is not valid UTF-8.
FLK-0940	An `xml_converted` node’s mapped body is not a structured object. Converted XML needs an object to serialize under `root_element`.
FLK-0941	The mapped body could not be encoded as XML. Review the structure the mappings produce.
FLK-0958	A node’s `content_digest` is malformed or does not resolve to a non-blank digest. Provide a 64-character hexadecimal SHA-256 value.
FLK-0959	The assembled request body does not match `content_digest`, or no body was assembled. Flowker rejects the request before any network call.

Concurrency errors

Code	What it means
FLK-0350	The resource state changed concurrently. Retry with the latest version.

Webhook errors

Code	What it means
FLK-0360	The webhook path is already registered by another active workflow. Choose a different path, or deactivate the conflicting workflow.
FLK-0361	No webhook is registered for this path and method. Verify the webhook path and method, and try again.
FLK-0363	The webhook request body must not exceed 1 MB. Reduce the payload size.

Webhook trigger contract errors

The API returns these errors when you save a webhook trigger’s input_contract or activate the workflow. It also returns them during validation of an incoming payload against the contract.

Code	What it means
FLK-0930	The trigger’s `input_contract` is `xsd`, but its `xsd_schema_id` does not resolve to a stored XSD schema.
FLK-0931	The trigger’s `input_contract` is `openapi`, but its `openapi_schema_id` does not resolve to a stored OpenAPI schema.
FLK-0932	The referenced OpenAPI schema declares no operation matching the trigger’s `operation_path` and `operation_method`.
FLK-0933	The matched OpenAPI operation declares no JSON request body, so it cannot validate an incoming payload.
FLK-0934	The webhook trigger’s configuration does not match the trigger schema. The schema is closed, so the trigger fails when it omits `path` or `method`, misses a field its selected `input_contract` mode requires, names another mode’s schema id or operation field, or carries a key or a value the schema does not accept. Check this error first when you configure a webhook trigger.
FLK-0935	The incoming payload is well-formed JSON but does not conform to the operation’s request-body schema.
FLK-0936	The OpenAPI schema cannot be deleted because one or more active workflows reference it from a webhook trigger. References from draft or inactive workflows do not block the delete.
FLK-0957	The trigger’s optional `accepted_headers` declaration is invalid. Use a list of valid, non-blank, non-duplicate header names; credential-bearing names are refused.

External OpenAPI request and configuration errors

Code	What it means
FLK-0954	A required `header` or `query` parameter for an external OpenAPI operation found no value. The node fails before Flowker sends a request.
FLK-0955	An `external_openapi` provider configuration has a malformed `config.headers` block. Use valid, non-blank, case-insensitively unique header names with string values.

XSD schema errors

Code	What it means
FLK-0700	The requested XSD schema does not exist. Verify the schema ID and try again.
FLK-0701	An XSD schema with this name and version already exists. Choose a different name or version.
FLK-0702	The uploaded content failed XSD validation. Verify the schema document.
FLK-0703	The XSD schema file exceeds the 1 MiB limit. Reduce the file size.
FLK-0704	The XSD schema cannot be deleted because one or more workflow nodes reference it.
FLK-0710	The `name` field is required. Provide a name for the XSD schema.
FLK-0711	The `version` field is required. Provide a version for the XSD schema.
FLK-0712	The schema content is required. Upload the XSD document.
FLK-0720	The XML validation service is unreachable or returned a fault, so the payload could not be validated. Flowker rejects the request rather than accepting unvalidated XML.

External OpenAPI schema errors

These errors apply to the OpenAPI schemas you store per tenant and reference from triggers, provider configurations, and nodes.

Code	What it means
FLK-0807	The `name` field is required. Provide a name for the OpenAPI schema.
FLK-0808	The `version` field is required. Provide a version for the OpenAPI schema.
FLK-0809	The OpenAPI schema name exceeds the maximum allowed length. Reduce the name size.
FLK-0810	The OpenAPI schema version exceeds the maximum allowed length. Reduce the version size.
FLK-0811	The requested OpenAPI schema does not exist. Verify the schema ID and try again.
FLK-0812	An OpenAPI schema with this name and version already exists. Choose a different name or version.
FLK-0813	The schema content is required. Upload the OpenAPI document.
FLK-0900	The uploaded bytes do not parse as a valid OpenAPI 3.x document, or the document declares no operation.
FLK-0901	The uploaded OpenAPI schema exceeds the 8 MiB limit. Reduce the file size.
FLK-0902	The stored schema declares no operation matching the requested path and method. Verify the path and method.

OpenAPI spec registry errors

These errors apply to the shared OpenAPI spec registry, which pins the spec version Flowker uses to enrich a service’s output schemas.

Code	What it means
FLK-0801	The version-pin request is missing the service or the version. Provide both.
FLK-0802	The uploaded bytes do not parse as a valid OpenAPI 3.x document. Verify the spec.
FLK-0803	A spec is already stored for this service and version. Versions are immutable — upload a new version.
FLK-0804	The schema registry has no storage configured, so the upload cannot be accepted.
FLK-0805	The uploaded spec exceeds the registry size cap. Reduce the file size.
FLK-0806	The service or version path identifier is malformed. Remove empty values, slashes, `..`, control characters, and leading dots.

Scheduled occurrence errors

Code	What it means
FLK-0755	The occurrence is not in a state that can be run or discarded. Check its current state.
FLK-0760	The requested scheduled occurrence does not exist. Verify the occurrence ID and try again.

Getting started

Catalog API

Workflows API

Schedule API

Executions API

Dashboards API

Executor Configurations API

Provider Configurations API

Schema Registry API

OpenAPI Schemas API

XSD Schemas API

Webhooks API

Error handling

Flowker error list

Error format

Field definitions

Field-level error details

Errors on webhook routes

General errors

Request validation errors

Entity errors

Workflow errors

Workflow condition errors

Catalog, executor, and trigger errors

Executor configuration errors

Provider configuration errors

External OpenAPI provider configuration errors

Provider schema binding errors

Workflow execution errors

Outbound request errors

Concurrency errors

Webhook errors

Webhook trigger contract errors

External OpenAPI request and configuration errors

XSD schema errors

External OpenAPI schema errors

OpenAPI spec registry errors

Scheduled occurrence errors

​Error format

​Field definitions

​Field-level error details

​Errors on webhook routes

​General errors

​Request validation errors

​Entity errors

​Workflow errors

​Workflow condition errors

​Catalog, executor, and trigger errors

​Executor configuration errors

​Provider configuration errors

​External OpenAPI provider configuration errors

​Provider schema binding errors

​Workflow execution errors

​Outbound request errors

​Concurrency errors

​Webhook errors

​Webhook trigger contract errors

​External OpenAPI request and configuration errors

​XSD schema errors

​External OpenAPI schema errors

​OpenAPI spec registry errors

​Scheduled occurrence errors

Error format

Field definitions

Field-level error details

Errors on webhook routes

General errors

Request validation errors

Entity errors

Workflow errors

Workflow condition errors

Catalog, executor, and trigger errors

Executor configuration errors

Provider configuration errors

External OpenAPI provider configuration errors

Provider schema binding errors

Workflow execution errors

Outbound request errors

Concurrency errors

Webhook errors

Webhook trigger contract errors

External OpenAPI request and configuration errors

XSD schema errors

External OpenAPI schema errors

OpenAPI spec registry errors

Scheduled occurrence errors