API error: estimated request cost exceeds available balance despite having credits

[yxlyx]

Bug

Got this error mid-session:

api error: Estimated request cost ~237430 micro-USD exceeds available balance (concurrent reservations may have pushed it past your limit). Lower max_tokens or top up.

Expected behavior

The account has credits remaining, so requests should succeed. If a concurrent reservation temporarily pushed the balance past the limit, the request should either queue/retry or the error message should make clear it's a transient concurrent-reservation issue rather than implying the account is out of credits.

Actual behavior

Request was rejected outright. The message says to "lower max_tokens or top up" — but the account isn't actually out of credits, so the guidance is misleading.

Suggestions

• If concurrent reservations are the cause, consider releasing/holding them more conservatively so a single large context doesn't block the whole balance.
• Distinguish "genuinely out of credits" from "temporarily reserved by concurrent operations" in the error message.
• Optionally auto-retry once after a short backoff when the cause is a transient reservation.

Context

• Was running a long web-dev redesign session (lots of context tokens accumulated)
• Happened on a normal model round-trip, no unusual request size
• Credits were still present in the account

[yxlyx]

Fresh reproduction from the same long session on 2026-07-23:

• A workflow fan-out/synthesis attempt returned only Synthesize root causes (no result — task failed).
• Retrying as four direct parallel subagent calls caused all four to fail with ApiError.
• In harness.trace.jsonl, each subagent API event has ms: 0, context_tokens: 0, resp_bytes: 0, and is_error: true; the four requests were only ~5.6–5.8 KB each.
• Repeating them produced the same immediate failures.

This strongly supports a reservation/concurrency admission problem rather than genuinely exhausted account credits. The harness should avoid reserving all parallel calls when aggregate reservation exceeds balance, degrade concurrency, queue them, or return the underlying billing error instead of a generic ApiError.

[justrach]

Status split, verified 2026-08-01: the 'generic ApiError' half of this is fixed — since e8a35e0 (#287/#299, 2026-07-31) the child's verbatim billing error travels to the parent/workflow output, and classifyFailure treats insufficient_credits as a retry-safe quota failure with an explicit backoff note (src/subagent_run.zig:86,123). What remains open is the gateway half: reserveCredits still admits on worst-case estimateMaxCostMicroUsd atomically and returns a blunt 402 with no transient-vs-exhausted distinction and no queue (zigrepper services/codegraff-gateway/src/credits.ts:18-36 — unchanged since 2026-07-04), plus harness-side concurrency degradation under billing pressure. Keeping open for those; the gateway piece may deserve a twin issue in zigrepper where that code lives.

[justrach]

Progress: the harness half is fixed on main — subagent_run.zig now classifies credits/billing errors as .quota (retry-safe) and propagates the verbatim provider error instead of a generic failure. The remaining half (the balance-estimation 400 itself) lives in the gateway (zigrepper repo), not here.