API Errors & Auto-Retry

Sometimes a turn dies through no fault of yours or the agent’s: the provider returns a 500, the network drops, an upstream endpoint is briefly unavailable. Before this automation existed, such a session just sat there — the tile said “finished” (or kept working forever), and the error scrolled away in the terminal. Now vord notices the failed turn and, if you leave the switch on, simply tries again.

What counts as a provider error

vord reads each agent’s own error channel — transcript markers, rollout records, structured events — not the rendered terminal screen:

• Claude marks a failed API turn in its transcript; vord reads that marker.
• Codex ends the turn with an error record in its rollout file.
• Kimi logs turn failed with the provider’s error message, and from wire protocol 1.5 on writes the same failure into its wire record; vord pairs it with the failing request to know the cause. Kimi’s own silent in-turn retries are left alone — only a turn that actually died counts. A dead kimi turn no longer settles as “finished”: vord reads the record as an ending without a result, so a kimi session that failed is never reported as done — not on the tile and not to an agent that started it as a child.
• OpenCode reports errors as typed session events, including its own retry attempts; vord distinguishes “OpenCode is retrying itself” (the session keeps working) from “the turn is dead”. One retry is not work, though: when OpenCode’s retry status names a quota reason (account_rate_limit, free_tier_limit), says “usage limit”, or schedules the next attempt more than ten minutes away, OpenCode is sleeping until a quota resets — vord shows that as a usage limit with OpenCode’s own return time, not as a green working tile.
• Grok does not expose a usable error signal yet; failed grok turns still end as “finished” until its CLI provides one.
• Muse reports a failed turn through its session protocol, including typed errors such as needing to sign in again (authRequired). An authentication problem is never retried — sign in again with muse login or META_API_KEY.

Three things never trigger a retry: a usage limit (that has its own automation, see Usage Limits & Auto-Continue), an authentication problem (you need to sign in again — retrying can’t fix that), and a turn you cancelled yourself.

What the retry does

1. vord waits a moment — 10 seconds for the first attempt, then 30, then 90.
2. It sends a short continuation message so the agent picks the work back up. The text is configurable; the default tells the agent plainly that the previous attempt failed with a provider error.
3. A successfully completed turn resets the counter. After 3 failed attempts for the same error, vord stops and tells you — a Mac notification, a push to a paired iPhone, and an Inbox entry carrying the original error text. No silent give-up, no modal dialog.

The retry never interrupts you: it never fires while a question or permission box is open or while the agent is already working — for example because you stepped in and sent a message yourself, which also cancels the pending retry. And it always yields to the usage-limit automation if the session is rate-limited.

While a box stays open, vord checks again after 10 seconds, then with growing gaps of up to five minutes. If the box is still open after an hour, vord stops retrying and tells you the same way as after the third failed attempt.

Settings

Settings → Agents → Automation → “Retry after API errors” — on by default, with the attempt cap fixed at 3 and the message editable. Turning it off doesn’t hide failures: each dead turn still produces one Inbox entry with the error text.