Approval Required

approval-required · 202

A person must approve this call before it runs, so the API held it and changed nothing.

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.

Common causes

  • The call carries an X-Ghaym-Agent, X-Ghaym-Session or X-Ghaym-Intent header, 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 standard or strict, 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. Under sandbox, 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 but sandbox. operation is then session.rollback.

How to fix the call

  • Don't send the call again: once it is approved, the API runs the held call itself. A resend with the same X-Ghaym-Session gets the same pending approval back, and one without a session is held as a second approval.
  • Poll pollUrl until its status is no longer pending: it ends approved, denied or expired. From the CLI, run ghaym cloud approvals wait <id>; the CLI exits with code 6 when a call is held.
  • Tell the user what is waiting: operation names the call, and the approval expires at expiresAt.
  • To check a call without holding anything, send it with ?dryRun=true first. A dry run is never held.

Example response

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"
}