parent_headroom_exhausted: The parent has no room for this child

An agent gateway asked the plugin wire for a child stream (POST /plugin/v1/streams/{id}/children), and the parent cannot fund it. The parent's free headroom is its remaining cap minus what its open children still hold, and never more than the network's remaining headroom. Two cases refuse:

An unsigned request for more than the free headroom is not refused: the child opens with the free headroom as its cap. A refused request opens nothing and is recorded as a cap refusal on the parent.

The dynamo-guard host (4.2.0 and later) serves the same route for its session's stream and answers this code, with the same body, when the free headroom is zero. It takes no signed hops.

What to do

On the wire

HTTP 402.

{
  "error": "the parent has no headroom for a child (fail closed)",
  "reason": "parent_headroom_exhausted"
}

For a signed hop above the headroom the error text is "the signed hop's cap exceeds the parent's headroom (fail closed)".

See all error codes.