Do not retry every unknown failure.PI_AI_ERROR is a catch-all that can contain permanent, billable, or policy-relevant failures.

Prove four independent gates.

Provider

Transient status, type, request ID, and delay.

Classifier

Stable Harness failure code.

Policy

Selected route's resolved retry contract.

Executor

Durable schedule and started events.

rc.8 normal policy.

Eligibleempty · rate · server · timeout · transport

Five retries after the first request when policy is omitted.

Backoff500ms → 10s

Bounded exponential delay with 10% symmetric jitter.

UnknownPI_AI_ERROR

Delegated without retry by default.

Do not add the catch-all to retryableCodes.

Recognize a verified word-bounded transient marker narrowly, or normalize the provider gateway response.

Read the event pair.

llm/retry

Retry scheduling became durable.

llm/retry-started

The wait completed and the attempt began.

Scheduled only

Cancellation or disposal may have won.

No events

Classification, policy, exhaustion, or call surface won.

Primary evidence.

Keep the complete retry runbook.

The canonical guide includes the classifier table, provider and route evidence, bounded recovery, durable event interpretation, narrow source fix, collision tests, and fifteen acceptance gates.

Read the complete runbook