Ports and branching: how a flow chooses its path

A port is a named exit of a node. Which ports must be connected, and what happens when a node leaves through one that is not.

3 min read

A node finishes by leaving through one of its ports — its named exits. A connection starts at a port and leads to the next node, so the port a node leaves through is the branch the flow takes.

One port, one connection

Most nodes have a single port, Default. They do their work and pass the execution on. A node that makes a decision has a port for each outcome.

Here Condition leaves through Met or through Not met, and each of the two leads to its own node.

A port has at most one connection. A second connection from the same port is an error, and the flow is not published.
Several connections may arrive at one node. Branches join again where it suits the flow.
The API names a port by its code — met, not_met, rate_limit. The builder shows its name in your language.

Required and optional ports

A required port must be connected. A flow with a required port that leads nowhere is not published.

Most ports are required. The optional ones are the ports a node leaves through when a call was refused or failed.

AI Model — Error, Pool exhausted and Deny are optional. Only Success is required.
Budget Check — Deny is optional.
Http Request — Error is optional.

A port that leads nowhere

An optional port may be left without a connection. When the node then leaves through it, there is no branch to follow, and what the branch would have handled becomes the answer of the whole request.

A refusal is answered to the caller as the refusal it is. When Budget Check says no and has no Deny branch, the caller gets budget_exceeded or policy_denied, and the execution ends as rejected.
An error is answered to the caller as that error, and the execution ends as failed.

One port has a second way out. When the attempts of a model call run out without an answer, AI Model leaves through Pool exhausted. When that port has no connection and Error has one, the execution takes the Error branch. When neither is connected, the caller gets the error pool_exhausted.

The publish check warns about two of these ports, because leaving them out changes what your application receives.

AI Model without an Error branch — a provider error fails the whole operation.
Budget Check without a Deny branch — a refusal goes to the caller instead of following a branch.

A warning does not stop the publication.

unrouted_port is the code of an execution that left a node through a port with no connection and had neither an error nor a refusal to answer with. The check of required ports is there to keep a published flow away from it.

Nodes without ports

Return Response and Reject Request have no ports, because they end the path. Every path of a flow has to end at one of them. Any other node that a path reaches and that has no connection going out of it is an error, and the flow is not published.

The ports of every node

Port	Key	Nodes
Default	`default`	Request must be connected Estimate Cost must be connected Budget Check «Allow» must be connected Reserve Budget must be connected Capture & Release must be connected Trace Note must be connected Transform must be connected Cache Write must be connected Fallback must be connected Queue must be connected Http Request must be connected
Success	`success`	AI Model must be connected
Error	`error`	AI Model Http Request
Pool exhausted	`rate_limit`	AI Model
Deny	`deny`	Budget Check AI Model
Met	`met`	Condition must be connected
Not met	`not_met`	Condition must be connected
Hit	`hit`	Cache Lookup must be connected
Miss	`miss`	Cache Lookup must be connected
Approved	`approved`	Require Approval must be connected
Rejected	`rejected`	Require Approval must be connected

Where to go next

How a flow is built — the entry node, the terminal nodes and the groups of the palette.

Built from openapi b070e1f, sdk contract 5cc7055, php ae4a53b, node 84bc62d