child_adopt_refused: The on-chain child does not match the prepared child adoption

POST /owner/v1/streams/:id/children/adopt reads every prepared fact of the child back from the version 2 vault before it records anything: the child's budget, parent stream, sender, service node, session key, rate, cap and holdback, that it binds no terms, and that neither it nor its parent is revoked and that it has settled nothing. When one of them differs, or the preparation has expired or was used for another on-chain stream, the adoption is refused and nothing is recorded. An unused preparation stays usable until its expiresAt. POST /owner/v1/streams/:id/children/adopt-prepare answers the same code, with check adoption_expired, when its requestRef repeats a preparation that expired unused.

errorDetail.check names the check that failed, and errorDetail.param names the request field it concerns (streamRef, txHash or adoptionId). Both child adoption routes send errorDetail to every client, with or without Dynamo-Error-Detail: 1; detail also names the check in words.

checkWhat differs
stream_existsNo stream with this id exists on this deployment's vault
stream_takenThe on-chain stream is already recorded on this deployment
tx_receiptThe transaction has no receipt, reverted, or did not open exactly one stream on this vault
child_budgetThe stream belongs to another on-chain budget
child_parentThe stream has another parent stream
child_openerThe stream (or transaction) was sent by another address than the parent stream's serviceNode
child_service_nodeThe child pays another service node
child_session_keyThe child's session key is not the one the core issued
child_rateThe child's rate differs
child_capThe child's cap differs
child_holdbackThe child's holdback differs
child_termsThe child binds terms or a breach signer the preparation did not
child_revokedThe child is revoked
child_settledThe child has already settled value
parent_revokedThe parent stream is revoked on chain
adoption_expiredThe preparation passed its expiresAt
adoption_usedThe preparation already adopted another on-chain stream

What to do

On the wire

HTTP 409, error type state_error. Nothing is recorded.

The routes were added in 1.8.0. A single-tenant core answers them whatever Dynamo-Version the request names. On the multi-tenant hosted tier, the front door refuses a request served below 1.8.0 with HTTP 404 version_unavailable before the core sees it; a request that names no version is served the account's default, which is 1.8.0 for new accounts.

Every client gets the detailed body:

{
  "error": "state",
  "reason": "child_adopt_refused",
  "detail": "…",
  "errorDetail": {
    "type": "state_error",
    "code": "child_adopt_refused",
    "message": "…",
    "param": "streamRef",
    "doc_url": "…/errors/child_adopt_refused.md",
    "fix": "the on-chain child does not match the prepared child adoption, or the preparation expired or was used (errorDetail.check names the fact); the parent agent sends exactly the prepared openStream from the parent stream's serviceNode, or prepares again (nothing was adopted)",
    "check": "child_cap"
  }
}

See all error codes.