Troubleshooting: Orby pending-action approval

When a turn proposes an action that changes data — send a message, reassign a conversation, pause a campaign — Orby does not run it on the spot. It registers a pending action and renders an approval card in the chat. The action executes only when an operator explicitly approves it, and the window closes five minutes after the proposal. Every failure in that window carries a stable PENDING_ACTION_* code; this page maps each one to its cause and its recovery. The full platform code list lives in the error reference; this page is the runbook for the approval path. Session-token and authorization failures on the same panel are on the sibling page, Orby operator errors.

1. Why an approval window exists

Every data-changing proposal lands in a pending_agent_actions row and waits there until an operator explicitly approves or rejects it. The row records the tool, the exact arguments, and the proposing operator, so what you approve is a concrete, auditable payload — not “whatever the model meant.” Approval is a deliberate gate, not a formality: it keeps the operator in control of every write Orby performs. Approvals and rejections are audit-logged, including who acted and on which payload. The five-minute window exists so a stale proposal cannot be approved after its context has moved.

2. Code table

Code	HTTP	Cause	Fix
`PENDING_ACTION_NOT_APPROVABLE`	409	The row already left the `pending` state because someone approved, rejected, or cancelled it. The same code also fires when a retried approve hits an already-completed row — the second attempt refuses so the action never runs twice.	Ask Orby to re-issue the proposal. If a teammate may have acted first, check the action’s current state instead of re-approving blind — `GET /api/v1/orby/tool-actions/:id` returns the row’s status.
`PENDING_ACTION_RACE`	409	Two operators pressed approve or reject at the same time and yours was the loser.	Re-ask Orby for the proposal if you still want it done. Keep one operator as the approver to eliminate the race.
`PENDING_ACTION_EXPIRED`	409	The five-minute approval window elapsed before anyone acted. The expired row is cancelled so a later approve cannot slip a stale proposal through.	Ask Orby to propose the action again — a new card starts a new five-minute window. Mute the countdown only when you know you will approve.
`PENDING_ACTION_PERSIST_FAILED`	500	The runtime could not record the pending action at proposal time, so the tool was refused outright. This is fail-closed: a proposal that cannot be recorded never executes.	Retry the turn once. If it recurs, collect the `request_id` and escalate — the proposal write failed, not your request.

A sample envelope for a lapsed window — key on error.code, never on the message text:

{
  "error": {
    "code": "PENDING_ACTION_EXPIRED",
    "message": "Approval window elapsed before the operator acted.",
    "status": 409
  },
  "meta": {
    "request_id": "req_orby_0a1",
    "timestamp": "2026-09-16T09:41:12.388Z"
  }
}

3. Operator flow

Open the Orby chat where the proposal was made. The pending action card shows the tool, its exact arguments, and the id; a custom client reads the pending_action_id off the tool_pending SSE event.
To re-check whether the card is still live before approving, read the action — GET /api/v1/orby/tool-actions/:id returns the row’s status and its expires_at, so you can see the remaining window without guessing.
If the card is gone or the read says the action is done, rejected, or cancelled, do not re-submit the same approve call — ask Orby to re-issue the proposal and approve the fresh card. An approve on a non-pending row is exactly what returns PENDING_ACTION_NOT_APPROVABLE.
Assign approval to one operator. Pending actions belong to the proposing operator, so a teammate re-issuing the proposal is the clean way to hand a proposal over — not two people racing the same card.

4. Retry safety

Code	Retry class
`PENDING_ACTION_NOT_APPROVABLE`	Never retry the same approve call — re-ask for a fresh proposal.
`PENDING_ACTION_RACE`	Not retriable as-is; re-issue the proposal if still wanted.
`PENDING_ACTION_EXPIRED`	Not retriable; re-issue the proposal.
`PENDING_ACTION_PERSIST_FAILED`	Retry the turn once, then escalate with the `request_id`.

None of the 409s is retriable — they re-fail deterministically on repeat. The recovery is always “new proposal, approve promptly.” Only PENDING_ACTION_PERSIST_FAILED is a transient 500 worth a single retry.

When to escalate

Escalate to support when:

PENDING_ACTION_PERSIST_FAILED recurs after a single retry — the proposal write is failing, not your request.
A 409 code appears on a proposal you are certain nobody else touched — that contradicts the single-approver flow and is worth a trace.
The approval card disappears before the five-minute window visibly elapses.

Include the request_id from the meta block (or the error SSE event), the pending-action id when you have it, and the tool name. The request id threads through the turn, dispatch, and approval paths, so support can pull the executor-side trace without a back-and-forth.

Reference

Troubleshooting: Orby pending-action approval

Troubleshooting: Orby pending-action approval

1. Why an approval window exists

2. Code table

3. Operator flow

4. Retry safety

When to escalate

See also

​Troubleshooting: Orby pending-action approval

​1. Why an approval window exists

​2. Code table

​3. Operator flow

​4. Retry safety

​When to escalate

​See also

Troubleshooting: Orby pending-action approval

1. Why an approval window exists

2. Code table

3. Operator flow

4. Retry safety

When to escalate

See also