approval_required: The action is waiting for approval
The open, delegation or reservation crossed one of the approval thresholds (capAbove, reserveAbove or depthAbove) of a governing mandate or of a policy that governs the budget. Opens, delegations and reservations are held as a pending approval until the owner decides or it times out; nothing was opened or reserved. A direct meter without a reservation that crosses reserveAbove (or a policy's approval rule) is refused with this code instead, nothing billed and no approval created: on an approval-gated stream, reserve first.
What to do
- Send
Dynamo-Error-Detail: 1to receiveapprovalIdandapprovalExpiresAtwith this refusal. - The owner approves or rejects it in the console, with
dynamoprotocol approvals approve <id>, or withPOST /owner/v1/approvals/{id}/approve. - A held stablecoin open on contract v2 that the SDK keyed is approved only from the client that opened it (
budget.approve), because only that client holds the stream's session key. The console and the approvals widget offer reject only for it (clientKeyed: trueat Dynamo-Version 1.8.0). - Once approved, the action has run: the approval's
resultRefis the new stream id (open) or reservation id (reserve). An approval waives only the threshold it was raised for: if another threshold also applies, the approval endsfailedwithresultCodeapproval_requiredandresultRefnaming a new pending approval for it. An approval is used once. Retrying the same request while it is pending creates no second approval.
On the wire
HTTP 409, error type approval_required.
A client that does not send Dynamo-Error-Detail: 1 to a 1.3.0 route sees the legacy reason cap, and no approvalId, so its response shape is unchanged. Opted-in clients and the routes that always answer in detail (such as payment authorizations) see approval_required with approvalId and approvalExpiresAt. A child open on the plugin wire (POST /plugin/v1/streams/{id}/children) that is held answers HTTP 409 {"error": "child open refused (fail closed)", "reason": "approval_required"}, with no approval id.
With Dynamo-Error-Detail: 1:
{
"error": "halted",
"reason": "approval_required",
"streamId": "stm_…",
"detail": "…",
"approvalId": "apr_…",
"approvalExpiresAt": "1900000300",
"errorDetail": {
"type": "approval_required",
"code": "approval_required",
"message": "…",
"param": null,
"doc_url": "…/errors/approval_required.md",
"fix": "the action is held for the owner's approval; approve it in the console or with the approvals route"
}
}
Approval re-checks everything except the threshold that held it. If anything else changed meanwhile (a freeze, a cap amendment), the approval ends as failed with resultCode naming why.
See all error codes.