request-approval

• ApprovalError: only when an SDK waits for the decision and the approval was rejected, expired or went overdue, or no decision arrived in time.

A real response, captured from a live call to request-approval:

{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000046\",\"result\":{\"expires_at\":\"2026-10-02T12:10:43.940639977Z\",\"hard_expires_at\":\"2026-10-05T12:10:43.940639977Z\",\"id\":\"ar_6abbaac3fb130d22ba652a6f\",\"reference\":\"mcp-order-77\",\"risk\":\"low\",\"status\":\"pending\"}}"
    }
  ],
  "isError": false
}

{
  "lifecycle_id": "qlc_000043",
  "result": {
    "expires_at": "2026-09-30T12:10:11.253931788Z",
    "hard_expires_at": "2026-10-01T12:10:11.253931788Z",
    "id": "ar_6abbaaa3fb130d22ba652a6c",
    "reference": "refund-1042",
    "risk": "high",
    "status": "pending"
  }
}

// the object you get back IS the result — there is no `.result` to read
{
  expires_at: '2026-09-30T12:11:05.873226724Z',
  hard_expires_at: '2026-10-01T12:11:05.873226724Z',
  id: 'ar_6abbaad9fb130d22ba652a78',
  reference: 'campaign-c12',
  risk: 'high',
  status: 'pending'
}

// The TS SDK names these camelCase — lifecycleId, traceId — where Python uses
// lifecycle_id and trace_id. Both are non-enumerable: readable, but omitted by
// Object.keys() and JSON.stringify(). `result.lifecycleId` here is undefined.
result.lifecycleId // 'qlc_000055'

# a dict subclass; `result` is already unwrapped
{
 "expires_at": "2026-10-01T12:10:55.938521644Z",
 "hard_expires_at": "2026-10-03T12:10:55.938521644Z",
 "id": "ar_6abbaacffb130d22ba652a72",
 "reference": "inv-9",
 "risk": "medium",
 "status": "pending"
}

out.lifecycle_id  # 'qlc_000049' — an attribute, not a key

Read the decision with get-approval, or let an SDK wait for it. For how approvals are decided and resumed, see policy and approvals.

reference is your app's own id for the thing being approved: an order number, a refund id, a campaign id. Calling again with the same reference while the approval is still open returns that same approval rather than opening a second one, so a retry or a second worker never puts the same request in front of an approver twice. Once the approval is decided, the same reference opens a new approval. A reference belongs to your project: the same reference in another project is a separate approval there.

• high: deadline (expires_at) 24 hours, expires (hard_expires_at) 48 hours.
• medium (default): deadline (expires_at) 48 hours, expires (hard_expires_at) 96 hours.
• low: deadline (expires_at) 72 hours, expires (hard_expires_at) 144 hours.

Past expires_at the approval is overdue: it stays in the Inbox and can still be decided. At hard_expires_at it is expired and can no longer be decided.

With choices, the Inbox shows one button per choice in place of Approve and Reject. Picking one approves the request with that choice, so the status is approved whichever was picked: read choice to act on it, and include an option such as hold when the approver needs a way to say no.

The organization, the project and the requester are not arguments you pass. They come from the credential you authenticated with: an API key requests as the admin who created it, and an SDK session requests as the user who signed in. org_id, organization_id, project_id, projectID, requested_by, requester and user_id are refused if you send them.

• id (string): The approval id, ar_.... Pass it to get-approval.
• status (string): pending for a new request. A repeat call returns the open approval's current status.
• risk (string): low, medium or high.
• expires_at (string): The deadline. After it the approval is overdue.
• hard_expires_at (string): When the approval expires.
• reference (string): The reference you passed.

Both SDKs can wait for you. With wait set they poll get-approval until the approval reaches a final status. approved returns the approval as get-approval shows it. rejected, expired and overdue raise ApprovalError with the status in the message (approval rejected) and the approval in raw. If nothing final arrives within timeout seconds (default 600, checked every poll seconds, default 5), ApprovalError is raised too, and the approval stays open for you to read later.

import { ApprovalError, Fabric } from '@wexa-fabric/sdk'

const fabric = new Fabric()
try {
  const approval = await fabric.requestApproval({
    title: "Refund order 1042",
    reference: "refund-1042",
    wait: true,
    timeout: 3600,
    poll: 10
  })
  console.log(approval.decided_by, approval.decision_reason)
} catch (e) {
  if (!(e instanceof ApprovalError)) throw e
  console.log(e.message)
}

from wexa import ApprovalError, Fabric

fabric = Fabric()
try:
    approval = fabric.request_approval(
        title="Refund order 1042",
        reference="refund-1042",
        wait=True,
        timeout=3600,
        poll=10,
    )
    print(approval["decided_by"], approval.get("decision_reason"))
except ApprovalError as e:
    print(e)

Not marked consequential: asking for an approval is never itself held for approval, whatever the project's setting for consequential writes. The request is recorded in the approval audit trail when it is created and again when it is decided.