Limits And Recovery

Canonical runtime and payload limits for public flow authoring, plus recovery actions for common limit failures.

Quick Answer

Design flows to stay within hard limits, and prefer templates/persistence/chunking before raising payload size in runtime paths.

Core Flow Limits

Limit	Value	Notes
Max flow payload size	150 KB	Definition map only; excludes template/function bodies.
Max steps per flow	50	Total declared steps in a flow.
Max `flow/call-flow` nesting depth	5	Child-flow nesting guardrail.
Max templates total size	1 MB	Aggregate template content budget.
Max functions total size	1 MB	Aggregate function content budget.
Effective package budget	~2.1 MB	Combined payload + templates + functions.

Runtime Limits Per Run

Limit	Value	Notes
Max step executions	10000	Per run execution ceiling.
Max HTTP requests	50	Per run, across HTTP steps.
Max tracked LLM tokens per run (platform-managed keys)	100000	Accounting limit for platform-managed keys.
Platform-managed `:max-tokens` clamp per LLM call	10000	Applied only for platform-managed keys.
User-provided LLM keys `:max-tokens` clamp	Not clamped by platform	Provider/account limits still apply.
Max workflow duration	30 days	Hard run duration cap.
Max child flow invocations	25	`flow/call-flow` invocations per run.
Max fanout step executions	5	Total `:fanout` step executions per run.
Max fanout total items	100	Total items across all `:fanout` steps in one run.

Fanout And Child-Workflow Guardrails

Guardrail	Value	Notes
Max fanout width	25	Max items in one `:fanout` step.
Max async child fanout concurrency	5	`:max-concurrency` must be at most `5`; validation rejects larger values.
Async fanout item type	`:call-flow` only	All items in async mode must be child workflow items.
Mixed fanout modes	Not allowed	Do not mix legacy step items and `:call-flow` items in one `:fanout`.
Nested fanout items	Not allowed	`:fanout` items cannot themselves be `:fanout`.
Nested async child fanout depth	1	Descendant async child fanout is rejected.
Child start confirmation	Required	Parent waits for child start confirmation before treating spawn as successful.

Wait And Approval Limits

Limit	Value	Notes
Default wait timeout	24h	Applies when timeout is omitted.
Max wait timeout	30 days	Hard cap for wait duration.
Checkpoint timeout default	24h	Review checkpoint timeout can be set up to 30 days.

Polling Limits (`flow/poll`)

Limit / Rule	Value	Notes
Max poll timeout	1h	Hard timeout ceiling for `flow/poll`.
Max poll attempts	100	Hard attempt ceiling for `flow/poll`.
Required bound	At least one of `:timeout` or `:max-attempts`	Unbounded polling is rejected.
Required condition + backoff validation	`:return-on` required	Backoff shape is validated (for example `:linear` requires `:step`).

Step Result And Persistence Limits

Limit	Value	Notes
Inline result threshold	512 KB	Results above this should usually use `:persist`.
Max step result size	1 MB	Hard per-step output cap.
DB result max bytes	1 MB	Cap for database step result payload bytes.
DB result max rows	5000	Cap for row count returned by DB steps.
Code step input max	1 MB	Hard cap on `:function` step `:input`.
Notify payload max	1 MB	Hard cap for notify payload body.
Authoring recommendation	Prefer `:persist` for unknown/growing outputs	Many real flows exceed inline limits quickly.

Webhook And Ref Loading Limits

Limit	Value	Notes
Webhook payload max	50 MB	General webhook body size ceiling.
Signed multipart webhook payload max	5 MB	Applies to signed multipart uploads.
Raw MIME webhook payload max	50 MB	Raw MIME ingestion ceiling.
Ref load into LLM content	100 KB	Ref content cap when injected into LLM fields.
Ref load into code step	1 MB	Ref content cap for code step loading.
Ref load into HTTP body	10 MB retained / 20 MB ephemeral tier	Tier-dependent HTTP body ref loading limit.
Persist write cap	50 MB retained / 4 GB ephemeral tier	Tier-dependent blob persistence write limit.

Config Warning Thresholds

Threshold	Behavior	Recommendation
~1 KB per step payload	Non-blocking warning starts around this size	Move large literals into templates.

Failure Recovery Patterns

When you hit size/limit validation errors, apply these patterns first:

Validation error	First recovery actions
`Flow payload too large`	Move large inline content into `:templates` and `:functions`. Replace large literals in `:flow` with template/function refs.
`Result too large` / `Query result too large` / `DB row limit exceeded`	Paginate (`LIMIT`, cursor loops). Aggregate/filter in database first. Persist artifacts and pass refs instead of full payloads.
`Blob reference too large for ...`	Reduce blob size before loading it into a step. For user downloads, return signed links instead of loading full content into flow memory.
`Code step :input too large`	Pass compact subsets into code steps. Move heavy processing to data layer or external compute. Orchestrate in smaller batches.
`Fanout width exceeds limit` / `max fanout total items exceeded`	Reduce batch size. Split work into multiple parent runs or stages. Keep one `:fanout` bounded to independent child workflows.
`child-flows limit exceeded` / `Nested async child fanout is not allowed`	Keep async child fanout at one orchestration depth. Move deeper branching inside a single child flow. Use plain `flow/call-flow` for descendant orchestration.
`Wait timeout exceeds maximum`	Use shorter waits and multi-stage waits. Branch timeout outcomes explicitly (`:fail` or `:continue`).
`flow/poll timeout exceeds limit` / `flow/poll max attempts exceeded`	Reduce timeout and use staged polling (fast first poll, slower secondary poll). Increase interval and use explicit backoff. Prefer webhook/wait-signal patterns when callbacks are supported.

Recommended Authoring Checklist

Checklist item	Why
Add `:persist` when output size is uncertain	Prevents inline payload overflow as data grows.
Use templates for large request/prompt/SQL bodies	Keeps flow payload size stable and reviewable.
Keep waits bounded and keyed	Avoids unbounded waits and ambiguous resume paths.
Design webhook auth explicitly (`:auth {:type ...}`)	Prevents insecure/default webhook exposure.
Test largest expected payload paths, not just tiny happy-path samples	Catches real-world limit failures before production.