Approval Required
approval-required · 202
A person must approve this call before it runs, so the API held it and changed nothing.
All pages
The status is 202, not an error: the call was accepted and waits for a person to approve or deny it. Only a call that names an agent is held, and pollUrl is where the decision shows up.
Besides the members every error carries, this type adds approvalId, pollUrl, expiresAt, operation, projectId and approvalPolicy.
- The call carries an
X-Ghaym-Agent,X-Ghaym-SessionorX-Ghaym-Intentheader, so it counts as an agent's. A call without them counts as a person's, and is never held. - The project's approval policy is
standardorstrict, and the call deletes a project, an environment, a service or a domain, or applies staged changes that delete a variable, a service or a database copy. Undersandbox, nothing is held. - The policy is
strict, and the call launches a service whose projected monthly cost is above the set threshold. - An agent asks to roll back a session with
POST /v1/agent-sessions/<id>/rollback, under any policy butsandbox.operationis thensession.rollback.
- Don't send the call again: once it is approved, the API runs the held call itself. A resend with the same
X-Ghaym-Sessiongets the same pending approval back, and one without a session is held as a second approval. - Poll
pollUrluntil itsstatusis no longerpending: it endsapproved,deniedorexpired. From the CLI, runghaym cloud approvals wait <id>; the CLI exits with code 6 when a call is held. - Tell the user what is waiting:
operationnames the call, and the approval expires atexpiresAt. - To check a call without holding anything, send it with
?dryRun=truefirst. A dry run is never held.
json
{
"type": "approval-required",
"title": "Approval Required",
"detail": "This project's 'standard' approval policy holds project.delete for a human decision. Nothing has been changed. Poll /v1/approvals/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad402 until its status is no longer 'pending'; it expires at 2026-07-29T09:30:00.000Z.",
"status": 202,
"approvalId": "0199e0a3-6f21-7c4a-9d18-2b7c5f3ad402",
"pollUrl": "/v1/approvals/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad402",
"expiresAt": "2026-07-29T09:30:00.000Z",
"operation": "project.delete",
"projectId": "0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401",
"approvalPolicy": "standard",
"requestId": "req-1785231000000-4f7b2c9ae",
"timestamp": "2026-07-28T09:30:00.000Z",
"path": "/v1/projects/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401",
"method": "DELETE",
"instance": "DELETE /v1/projects/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401",
"docs": "https://ghaym.me/docs/errors/approval-required"
}