Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

chatgpt-new: plan errors follow OpenAI's recovery table

justrach268d321d1db7
diff --git a/docs/adr/0221-chatgpt-new-sign-in.md b/docs/adr/0221-chatgpt-new-sign-in.md
index f57d10ee..c0ab6fed 100644
--- a/docs/adr/0221-chatgpt-new-sign-in.md
+++ b/docs/adr/0221-chatgpt-new-sign-in.md
@@ -52,11 +52,15 @@ live on 2026-09-30, and all 45 checks behaved as documented:
intermittent (a repeated prefix sometimes reads back a few thousand
tokens); writes are never reported. `service_tier: "priority"` is accepted
and ignored.
-- **Errors.** Plan limits arrive as `subscription_sharing_usage_limit_exceeded`
- or `subscription_sharing_usage_unavailable`, on a 429 or mid-stream as
- `response.failed`. An expired access token is a 401 with
- `{"detail":{"error_code":"invalid_token"}}`. A rejected field is a 400
- whose `detail` names it.
+- **Errors.** OpenAI's recovery table for plan errors:
+ `subscription_sharing_usage_limit_exceeded` (429; the allowance is spent
+ until it resets), `…_usage_unavailable` and `…_user_unavailable` (503; retry
+ with bounded backoff), `…_user_not_eligible` and `…_route_not_supported`
+ (403), `…_unsupported_capability` (400), and `…_invalid_user` (401; sign in
+ again). Any of them can also arrive mid-stream as `response.failed`, and
+ OpenAI never moves the request to another billing path. An expired access
+ token is a 401 with `{"detail":{"error_code":"invalid_token"}}`. A rejected
+ field is a 400 whose `detail` names it.
- **Tokens.** The access token is a one-hour RS256 JWT (`aud`
`https://api.openai.com/v1`, `iss` `https://auth.openai.com`, the issued
`client_id`, the granted scopes, and opaque OpenAI metadata graff never
@@ -119,10 +123,14 @@ process rather than restarting anything.
prewarming when `GRAFF_WS_PREWARM` is set. One-shot and quiet turns stay on
HTTP, which never sends `previous_response_id`; a socket failure falls back
to it. A chat turn closes the socket it opened.
-- **Errors**: plan-usage codes fail fast, on a 429 or mid-stream, with a link
- to ChatGPT's usage settings. They are never retried as a flake and never
- fall back to another credential. `invalid_token` is an auth error: one
- refresh and retry, then the error says to sign in again.
+- **Errors** follow that table. A spent allowance fails fast, on a 429 or
+ mid-stream, with a link to ChatGPT's usage settings, and never falls back
+ to another credential. The two 503s take the overload ladder (three
+ retries, 1·2·4 s) and keep the credentials. Every other plan code, including
+ one graff does not know yet, stops the turn; no plan code is retried as a
+ gateway flake. `invalid_token` and `subscription_sharing_invalid_user` are
+ auth errors: one refresh and retry (never before `earliest_refresh_at`),
+ then the error says to sign in again.
- **Compaction**: the in-stream blob carries the prompts it pruned, so a
history holding a blob counts as conversation state and is saved.
- **The callback page** follows codegraff.com's design, embeds its images so it
diff --git a/src/agent_gateway_retry.zig b/src/agent_gateway_retry.zig
index 39e99d03..6d32a6be 100644
--- a/src/agent_gateway_retry.zig
+++ b/src/agent_gateway_retry.zig
@@ -28,6 +28,7 @@ const RetryPlan = http.RetryPlan;
const jitter = @import("retry_jitter.zig");
const util = @import("util.zig");
const policy = @import("agent_request_policy.zig");
+const quota = @import("agent_request_quota.zig");
const telemetry = @import("telemetry.zig");
const main_mod = @import("main.zig");
@@ -92,8 +93,9 @@ pub fn afterServerErrorOrParseReject(self: *Agent, etype: []const u8, code: ?[]c
// A structured terminal code outranks transient wording in the message.
// In particular, do not retry a model the gateway cannot serve even if
// its diagnostic also mentions capacity or a request-body parse error,
- // or a spent ChatGPT plan allowance whose message says "try again later".
- if (isModelUnavailable(code) or isStructuredOverflow(code) or policy.isPlanUsageLimit(code)) return false;
+ // or a ChatGPT plan code OpenAI says to stop on, such as a spent allowance
+ // whose message says "try again later" (ADR 0221).
+ if (isModelUnavailable(code) or isStructuredOverflow(code) or quota.isPlanStop(code)) return false;
if (try retryTransientServerError(self, etype, code, msg, server_retries)) return true;
if (try retryShortGatewayFlake(self, etype, code, msg, server_retries)) return true;
return retryBodyParseAfterTimeouts(self, msg, state);
@@ -119,8 +121,9 @@ fn isModelUnavailable(code: ?[]const u8) bool {
/// Do not treat invalid_request / auth / quota as a flake.
pub fn isShortGatewayFlake(etype: []const u8, code: ?[]const u8, msg: []const u8) bool {
// Gateway 110-byte follow-up. etype is often invalid_request_error, which
- // would otherwise hard-fail on the "invalid" needle. Auth/quota still die.
- if (isModelUnavailable(code) or isStructuredOverflow(code) or policy.isPlanUsageLimit(code)) return false;
+ // would otherwise hard-fail on the "invalid" needle. Auth/quota still die,
+ // and so does every ChatGPT plan code: its 503s have the transient ladder.
+ if (isModelUnavailable(code) or isStructuredOverflow(code) or quota.isPlanCode(code)) return false;
if (isBodyParseRejection(msg)) return true;
const hard = [_][]const u8{ "invalid", "authentication", "unauthorized", "insufficient", "quota", "permission", "tool_choice", "not found" };
for (hard) |n| {
@@ -189,6 +192,9 @@ pub const max_server_retries: usize = 3; // #opencode-parity: bounded retries fo
/// invalid-input errors are NOT transient and fall through to a hard fail.
pub fn isTransientServerError(etype: []const u8, code: ?[]const u8, msg: []const u8) bool {
if (isModelUnavailable(code)) return false;
+ // ChatGPT plan usage or user data temporarily unavailable (503, possibly
+ // mid-stream): keep the credentials and back off like an overload.
+ if (quota.isPlanTransient(code)) return true;
const needles = [_][]const u8{ "overloaded", "server_error", "server_is_overloaded", "token parsing" };
for (needles) |n| {
if (util.indexOfIgnoreCase(etype, n) != null) return true;
@@ -254,7 +260,7 @@ pub fn retryTransientServerError(self: *Agent, etype: []const u8, code: ?[]const
retries.* += 1;
self.partial_text.clearRetainingCapacity(); // fresh re-stream after the retry, no concat
const delay_ms = jitter.ms(self.io, serverRetryDelayMs(msg) orelse RetryPlan.delayMs(true, retries.* - 1)); // 1·2·4s, or the provider's wait; +jitter (#1274)
- const label = transientServerLabel(msg);
+ const label = if (quota.isPlanTransient(code)) "ChatGPT plan temporarily unavailable" else transientServerLabel(msg);
try announceTransientRetry(self, label, delay_ms, retries.*);
if (self.tracer) |tr| tr.note("retry", label);
if (telemetry.g_telem) |t| t.errorEvent("server_overloaded", if (msg.len > 0) msg else etype);
@@ -313,9 +319,11 @@ test "isShortGatewayFlake: internal/empty api_error retry; invalid/auth/quota do
try std.testing.expect(!isShortGatewayFlake("api_error", null, "model not found"));
try std.testing.expect(!isShortGatewayFlake("service_unavailable", "model_unavailable", "Codegraff cannot serve this model right now"));
try std.testing.expect(!isShortGatewayFlake("service_unavailable", "model_unavailable", "Malformed JSON in request body"));
- // A spent or unavailable ChatGPT plan allowance says "try again later"; it is not a flake.
+ // A ChatGPT plan code is never a flake, even when it says "try again later":
+ // its 503s ride the transient ladder and the rest stop.
try std.testing.expect(!isShortGatewayFlake("", "subscription_sharing_usage_unavailable", "Usage is temporarily unavailable"));
try std.testing.expect(!isShortGatewayFlake("", "subscription_sharing_usage_limit_exceeded", "Usage limit reached. Try again later."));
+ try std.testing.expect(!isShortGatewayFlake("api_error", "subscription_sharing_user_not_eligible", "Something went wrong"));
try std.testing.expect(isShortGatewayFlake("invalid_request_error", null, "Body must be valid JSON"));
try std.testing.expect(isShortGatewayFlake("api_error", null, "Malformed JSON in request body"));
try std.testing.expect(!isShortGatewayFlake("invalid_request_error", null, "invalid prompt"));
@@ -342,6 +350,10 @@ test "isTransientServerError (#opencode-parity): overload/server_error retry; qu
try std.testing.expect(!isTransientServerError("service_unavailable", "model_unavailable", "server overloaded; retry after 3 seconds"));
// a bare "Internal Server Error" stays on the shorter gateway-flake ladder
try std.testing.expect(!isTransientServerError("api_error", null, "Internal Server Error"));
+ // ChatGPT plan 503s back off like an overload (OpenAI's recovery table).
+ try std.testing.expect(isTransientServerError("", "subscription_sharing_usage_unavailable", "Usage cannot be checked."));
+ try std.testing.expect(isTransientServerError("", "subscription_sharing_user_unavailable", "User cannot be loaded."));
+ try std.testing.expect(!isTransientServerError("", "subscription_sharing_usage_limit_exceeded", "Usage limit reached."));
}
test "ADR 0148 (reverses #1019): token-parse 500 rides the transient server ladder, not overflow" {
diff --git a/src/agent_request.zig b/src/agent_request.zig
index 69064cc9..69dd9349 100644
--- a/src/agent_request.zig
+++ b/src/agent_request.zig
@@ -453,7 +453,7 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
// was terminal on this path: the session, and every
// auto-compaction it triggered, 401'd forever even after a
// successful /login.
- if (retryAfterAuthRefresh(self, msg, &auth_refreshed)) {
+ if (retryAfterAuthRefresh(self, failure.authText(), &auth_refreshed)) {
// PR #195: a mid-turn resend must re-anchor — the chained
// WS meter desyncs otherwise — and the held socket was
// dialed with the stale bearer besides.
diff --git a/src/agent_request_policy.zig b/src/agent_request_policy.zig
index b7da3148..0a51d373 100644
--- a/src/agent_request_policy.zig
+++ b/src/agent_request_policy.zig
@@ -18,7 +18,8 @@ pub fn isAuthError(msg: []const u8) bool {
util.indexOfIgnoreCase(msg, "expired") != null or
util.indexOfIgnoreCase(msg, "authentication") != null or
util.indexOfIgnoreCase(msg, "invalid_api_key") != null or
- util.indexOfIgnoreCase(msg, "invalid_token") != null; // OAuth bearer error (RFC 6750), the ChatGPT plan route's 401
+ util.indexOfIgnoreCase(msg, "invalid_token") != null or // OAuth bearer error (RFC 6750), the ChatGPT plan route's 401
+ util.indexOfIgnoreCase(msg, "subscription_sharing_invalid_user") != null; // the plan route's other 401: sign in again
}
test "isAuthError (#148): auth failures only, not credits/rate/other" {
@@ -28,6 +29,7 @@ test "isAuthError (#148): auth failures only, not credits/rate/other" {
try std.testing.expect(isAuthError("authentication_error"));
try std.testing.expect(isAuthError("invalid_api_key"));
try std.testing.expect(isAuthError("invalid_token"));
+ try std.testing.expect(isAuthError("subscription_sharing_invalid_user"));
// NOT auth — must never trigger a refresh loop
try std.testing.expect(!isAuthError("You have run out of credits or need a Grok subscription."));
try std.testing.expect(!isAuthError("rate limit exceeded"));
diff --git a/src/agent_request_quota.zig b/src/agent_request_quota.zig
index b57a4913..a46c20ae 100644
--- a/src/agent_request_quota.zig
+++ b/src/agent_request_quota.zig
@@ -1,6 +1,7 @@
-//! Quota caps and ChatGPT plan usage limits: a limit a retry cannot clear,
-//! unlike transient throttling. Split out of agent_request_policy.zig for the
-//! 600-line cap and re-exported there, so call sites keep saying `policy.`.
+//! Quota caps and ChatGPT plan errors: a limit a retry cannot clear, unlike
+//! transient throttling, and the plan codes OpenAI says to retry or stop on.
+//! Split out of agent_request_policy.zig for the 600-line cap; the quota
+//! checks are re-exported there, so their call sites keep saying `policy.`.
const std = @import("std");
const util = @import("util.zig");
@@ -19,31 +20,68 @@ pub const quota_cap_marker = "quota/billing cap";
pub fn isQuotaExceeded(body: []const u8) bool {
// ChatGPT plan usage limits (ADR 0221): stop, never retry into them.
- return util.indexOfIgnoreCase(body, plan_usage_code_prefix) != null or
+ return util.indexOfIgnoreCase(body, plan_limit_code) != null or
util.indexOfIgnoreCase(body, "insufficient_quota") != null or
util.indexOfIgnoreCase(body, "insufficient quota") != null or
util.indexOfIgnoreCase(body, "exceeded your current quota") != null or
util.indexOfIgnoreCase(body, "quota exceeded") != null;
}
-/// ChatGPT plan usage (ADR 0221): `subscription_sharing_usage_limit_exceeded`
-/// (the allowance is spent) and `subscription_sharing_usage_unavailable`. Both
-/// can arrive mid-stream as response.failed; neither clears in seconds.
-const plan_usage_code_prefix = "subscription_sharing_usage";
+// ChatGPT plan errors, as OpenAI's errors-and-recovery page classifies them
+// (ADR 0221). Only a spent allowance is a limit (429, resets after hours).
+const plan_limit_code = "subscription_sharing_usage_limit_exceeded";
pub fn isPlanUsageLimit(code: ?[]const u8) bool {
+ return std.mem.eql(u8, code orelse return false, plan_limit_code);
+}
+
+/// Any ChatGPT plan code. None of them is a gateway flake: each is either a
+/// temporary outage with its own ladder or a request to stop.
+pub fn isPlanCode(code: ?[]const u8) bool {
+ return std.mem.startsWith(u8, code orelse return false, "subscription_sharing_");
+}
+
+/// Usage or user data temporarily unavailable (503): keep the credentials and
+/// retry with bounded backoff, like an overload.
+pub fn isPlanTransient(code: ?[]const u8) bool {
const c = code orelse return false;
- return std.mem.startsWith(u8, c, plan_usage_code_prefix);
+ return std.mem.eql(u8, c, "subscription_sharing_usage_unavailable") or
+ std.mem.eql(u8, c, "subscription_sharing_user_unavailable");
+}
+
+/// Every other plan code stops the turn: a spent allowance (429), an account,
+/// workspace or policy that is not eligible (403), an unsupported route (403)
+/// or capability (400), or a user the route no longer accepts (401, which the
+/// auth refresh sees first). A new code stops too rather than spend usage.
+pub fn isPlanStop(code: ?[]const u8) bool {
+ return isPlanCode(code) and !isPlanTransient(code);
}
test "isQuotaExceeded (#opencode-parity): billing cap detected, transient throttle not" {
try std.testing.expect(isQuotaExceeded("{\"error\":{\"code\":\"insufficient_quota\",\"message\":\"You exceeded your current quota\"}}"));
try std.testing.expect(isQuotaExceeded("Quota Exceeded for this key"));
try std.testing.expect(isQuotaExceeded("{\"error\":{\"code\":\"subscription_sharing_usage_limit_exceeded\"}}"));
- try std.testing.expect(isQuotaExceeded("{\"error\":{\"code\":\"subscription_sharing_usage_unavailable\"}}"));
- try std.testing.expect(isPlanUsageLimit("subscription_sharing_usage_unavailable"));
- try std.testing.expect(!isPlanUsageLimit("rate_limit_exceeded") and !isPlanUsageLimit(null));
// transient rate-limit -> NOT a quota cap; must still retry
try std.testing.expect(!isQuotaExceeded("Rate limit reached. Please try again in 20s."));
try std.testing.expect(!isQuotaExceeded("429 too many requests"));
}
+
+test "ChatGPT plan codes follow OpenAI's recovery table" {
+ // A spent allowance stops; an unavailable usage or user check is a 503 to
+ // retry, not a limit; an ineligible account or unsupported request stops.
+ try std.testing.expect(isPlanUsageLimit("subscription_sharing_usage_limit_exceeded"));
+ try std.testing.expect(!isPlanUsageLimit("subscription_sharing_usage_unavailable"));
+ try std.testing.expect(!isQuotaExceeded("{\"error\":{\"code\":\"subscription_sharing_usage_unavailable\"}}"));
+ try std.testing.expect(isPlanTransient("subscription_sharing_usage_unavailable"));
+ try std.testing.expect(isPlanTransient("subscription_sharing_user_unavailable"));
+ try std.testing.expect(!isPlanTransient("subscription_sharing_usage_limit_exceeded"));
+ try std.testing.expect(!isPlanStop("subscription_sharing_usage_unavailable"));
+ for ([_][]const u8{
+ "subscription_sharing_usage_limit_exceeded",
+ "subscription_sharing_user_not_eligible",
+ "subscription_sharing_route_not_supported",
+ "subscription_sharing_unsupported_capability",
+ "subscription_sharing_invalid_user",
+ }) |c| try std.testing.expect(isPlanStop(c));
+ try std.testing.expect(!isPlanCode("rate_limit_exceeded") and !isPlanCode(null) and !isPlanStop(null));
+}
diff --git a/src/agent_responses.zig b/src/agent_responses.zig
index 47be07bf..6bf00486 100644
--- a/src/agent_responses.zig
+++ b/src/agent_responses.zig
@@ -12,6 +12,13 @@ pub const ResponsesFailure = struct {
message: []const u8,
code: ?[]const u8 = null,
request_id: ?[]const u8 = null,
+
+ /// The text to test for an auth failure. The ChatGPT plan route's
+ /// subscription_sharing_invalid_user 401 names it only in the code.
+ pub fn authText(f: ResponsesFailure) []const u8 {
+ const c = f.code orelse return f.message;
+ return if (policy.isAuthError(c)) c else f.message;
+ }
};
pub const ResponsesResult = union(enum) { ok: std.json.ObjectMap, err: ResponsesFailure };
@@ -130,16 +137,26 @@ pub fn failureDiagnostic(allocator: std.mem.Allocator, provider: []const u8, fai
// A spent ChatGPT plan allowance, often mid-stream (ADR 0221).
if (policy.isPlanUsageLimit(failure.code)) try w.writeAll(" \xe2\x80\x94 " ++ @import("oauth_chatgpt.zig").usage_hint);
// Reached only after the one refresh-and-retry could not help.
- if (std.mem.eql(u8, provider, "chatgpt-new") and policy.isAuthError(failure.message)) try w.writeAll(" \xe2\x80\x94 sign in again with `graff login chatgpt-new`");
+ if (std.mem.eql(u8, provider, "chatgpt-new") and policy.isAuthError(failure.authText())) try w.writeAll(" \xe2\x80\x94 sign in again with `graff login chatgpt-new`");
return allocator.dupe(u8, w.buffered());
}
-test "failureDiagnostic points a spent ChatGPT plan at its usage page" {
+test "failureDiagnostic points a spent ChatGPT plan at its usage page, a rejected user at sign-in" {
const a = std.testing.allocator;
const d = try failureDiagnostic(a, "chatgpt-new", .{ .message = "Usage limit reached.", .code = "subscription_sharing_usage_limit_exceeded" });
defer a.free(d);
try std.testing.expect(std.mem.startsWith(u8, d, "chatgpt-new api error [subscription_sharing_usage_limit_exceeded]: Usage limit reached."));
try std.testing.expect(std.mem.endsWith(u8, d, "https://chatgpt.com/settings/usage"));
+
+ // The route's other 401 names the failure only in its code.
+ const user: ResponsesFailure = .{ .message = "User cannot be verified.", .code = "subscription_sharing_invalid_user" };
+ try std.testing.expectEqualStrings("subscription_sharing_invalid_user", user.authText());
+ const signed_out = try failureDiagnostic(a, "chatgpt-new", user);
+ defer a.free(signed_out);
+ try std.testing.expect(std.mem.endsWith(u8, signed_out, "sign in again with `graff login chatgpt-new`"));
+ // A message that already reads as auth keeps it; a plan limit is no sign-in.
+ try std.testing.expectEqualStrings("Unauthorized", (ResponsesFailure{ .message = "Unauthorized", .code = "server_error" }).authText());
+ try std.testing.expectEqualStrings("Usage limit reached.", (ResponsesFailure{ .message = "Usage limit reached.", .code = "subscription_sharing_usage_limit_exceeded" }).authText());
}
fn writeDiagnosticField(w: *std.Io.Writer, raw: []const u8, max: usize) !void {
diff --git a/src/agent_ws_test.zig b/src/agent_ws_test.zig
index e739d17c..eb0aee73 100644
--- a/src/agent_ws_test.zig
+++ b/src/agent_ws_test.zig
@@ -84,7 +84,7 @@ test "the codex .responses arm refreshes auth and re-anchors before resending (#
try std.testing.expect(std.mem.indexOf(u8, arm, "responses.failureDiagnostic") != null and std.mem.indexOf(u8, arm, "resp_body[0..@min(resp_body.len, 600)]") == null);
- const call = std.mem.indexOf(u8, arm, "retryAfterAuthRefresh(self, msg, &auth_refreshed)") orelse
+ const call = std.mem.indexOf(u8, arm, "retryAfterAuthRefresh(self, failure.authText(), &auth_refreshed)") orelse
return error.ResponsesPathHasNoAuthRecovery;
const after = arm[call..];
const reanchor = std.mem.indexOf(u8, after, "closeCodexWs()") orelse return error.RetryDoesNotReanchor;