fix(logs): keep recognized bare upstream error classes in synthesized terminals

docs-site/src/content/docs/reference/management-api.md

@@ -282,6 +282,16 @@ Request logs retain `servedModel` when the upstream identifies the model that an
 shows `wire → served` when those identities differ; its tooltip preserves both values. Missing
 upstream model evidence remains absent rather than being inferred from the requested model.
 
+Failed request rows can include bounded `upstreamErrorType`, `upstreamErrorCode`, and
+`upstreamRequestId` diagnostics. On the Codex upstream WebSocket path, a bare error followed by
+EOF retains recognized rate-limit or overload codes in the synthesized failed terminal.
+Request logs record these as 429 for `rate_limit_exceeded` / `rate_limit_error`, or 503 for
+`server_is_overloaded` / `overloaded_error`. A recognized type without a code uses the same
+status; explicit unknown codes remain generic 502 failures. Bare-error status is provisional:
+a genuine completed, failed, or incomplete terminal replaces it before account-health recording.
+Refusal precedence is unchanged.
+This diagnostic mapping adds no automatic replay or retry.
+
 `GET /api/logs` accepts an optional opaque `cursor` from its previous response. The envelope preserves
 `logs`, `total`, `generatedAt` and `timeZone`, and adds `cursor` and `reset`. Without a cursor it returns
 the full filtered window. A valid unchanged prefix returns only appended rows; `reset: true` replaces

src/lib/errors.ts

@@ -639,6 +639,24 @@ export function adapterFailureFromMessage(message: string): { httpStatus: number
   return { httpStatus, error };
 }
 
+/** Narrow structured classes carried through a synthesized bare-error terminal. */
+export function recognizedUpstreamError(error: { type?: unknown; code?: unknown }):
+  { type: string; code: string; httpStatus: 429 | 503 } | undefined {
+  const code = typeof error.code === "string" ? error.code : undefined;
+  // An explicit unknown code must not gain a recognized class from its type or copy.
+  if (code !== undefined && !["rate_limit_exceeded", "rate_limit_error", "server_is_overloaded", "overloaded_error"].includes(code)) return undefined;
+  if (code === "rate_limit_exceeded" || code === "rate_limit_error"
+    || (code === undefined && error.type === "rate_limit_error")) {
+    return { type: "rate_limit_error", code: code ?? "rate_limit_exceeded", httpStatus: 429 };
+  }
+  if (code === "server_is_overloaded" || code === "overloaded_error"
+    || (code === undefined && error.type === "overloaded_error")) {
+    return { type: error.type === "overloaded_error" ? "overloaded_error" : "server_error",
+      code: code ?? "server_is_overloaded", httpStatus: 503 };
+  }
+  return undefined;
+}
+
 /** Map a terminal Responses error object to the HTTP status we record in /api/logs. */
 export function httpStatusFromTerminalError(error: {
   type?: string;
@@ -650,6 +668,8 @@ export function httpStatusFromTerminalError(error: {
   if (isCyberPolicyCode(error.code) || (error.message ? isCyberPolicyMessage(error.message) : false)) {
     return 400;
   }
+  const recognized = recognizedUpstreamError(error);
+  if (recognized) return recognized.httpStatus;
   if (error.type === "rate_limit_error" || error.code === "rate_limit_exceeded") return 429;
   if (error.type === "authentication_error" || error.code === "invalid_api_key") return 401;
   if (

src/server/relay-eager.ts

@@ -338,6 +338,8 @@ export function relaySseEagerBounded(
                 upstreamError,
                 terminalBoundary.upstreamRefusalCode(),
                 opts?.maskCredential,
+                terminalBoundary.upstreamErrorType(),
+                terminalBoundary.upstreamErrorCode(),
               );
             queuedBytes += upstreamErrorFrame.byteLength + terminalSentinel.byteLength;
             try {

src/server/relay.ts

@@ -6,6 +6,7 @@ import {
   isCyberPolicyCode,
   isCyberPolicyMessage,
   isTerminalRefusalCode,
+  recognizedUpstreamError,
   safetyRefusalCodeFromMessage,
   terminalRefusalFallbackMessage,
   upstreamErrorMessageFromPayload,
@@ -168,25 +169,28 @@ export function failedTailFrame(encoder: TextEncoder, err: unknown, maskCredenti
  * classifies this terminal by `error.code` alone and retries everything outside
  * its fatal set (codex-rs/codex-api/src/sse/responses.rs:423-450), so stamping
  * `upstream_server_error` on a refusal delivered it as a retryable disconnect
- * and drove the reconnect loop in #5176. Without a refusal code the terminal is
- * unchanged: a genuine transport failure stays retryable, which is what it is.
+ * and drove the reconnect loop in #5176. Without a refusal code the terminal
+ * carries only recognized rate-limit/overload classes; unknown codes stay generic.
  */
 export function upstreamErrorTailFrame(
   encoder: TextEncoder,
   message: string,
   refusalCode?: string,
   maskCredential?: (text: string) => string,
+  errorType?: string,
+  errorCode?: string,
 ): Uint8Array {
   return encoder.encode(
-    `event: response.failed\ndata: ${upstreamErrorFailedPayload(message, refusalCode, maskCredential)}\n\n`,
+    `event: response.failed\ndata: ${upstreamErrorFailedPayload(message, refusalCode, maskCredential, errorType, errorCode)}\n\n`,
   );
 }
 
-function upstreamErrorFailedPayload(message: string, refusalCode?: string, maskCredential?: (text: string) => string): string {
+function upstreamErrorFailedPayload(message: string, refusalCode?: string, maskCredential?: (text: string) => string, errorType?: string, errorCode?: string): string {
   const diagnostic = redactSecretString(message);
+  const recognized = recognizedUpstreamError({ type: errorType, code: errorCode });
   const error = {
-    type: refusalCode === undefined ? "upstream_error" : "invalid_request_error",
-    code: refusalCode === undefined ? "upstream_server_error" : (maskCredential?.(refusalCode) ?? refusalCode),
+    type: refusalCode === undefined ? (recognized?.type ?? "upstream_error") : "invalid_request_error",
+    code: refusalCode === undefined ? (recognized?.code ?? "upstream_server_error") : (maskCredential?.(refusalCode) ?? refusalCode),
     message: (maskCredential?.(diagnostic) ?? diagnostic).slice(0, MAX_TAIL_ERROR_MESSAGE_CHARS),
   };
   return JSON.stringify({
@@ -549,6 +553,8 @@ export function relaySseWithFailedTail(
                   upstreamError,
                   terminalBoundary.upstreamRefusalCode(),
                   opts?.maskCredential,
+                  terminalBoundary.upstreamErrorType(),
+                  terminalBoundary.upstreamErrorCode(),
                 ));
               controller.enqueue(doneFrame(encoder));
             }

src/server/request-log-terminal-status.ts

@@ -0,0 +1,154 @@
+import {
+  CYBER_POLICY_ERROR_CODE,
+  httpStatusFromTerminalError,
+  isCyberPolicyCode,
+  isCyberPolicyMessage,
+  isRateLimitOrQuotaFailureMessage,
+  recognizedUpstreamError,
+} from "../lib/errors";
+
+/** First bounded upstream diagnostics shared by request contexts and final rows. */
+export interface UpstreamErrorDiagnostics {
+  upstreamErrorCode?: string;
+  upstreamErrorType?: string;
+  upstreamRequestId?: string;
+}
+
+interface TerminalStatusContext extends UpstreamErrorDiagnostics {
+  terminalHttpStatus?: number;
+  terminalErrorCode?: typeof CYBER_POLICY_ERROR_CODE;
+}
+
+export interface UpstreamErrorPayload {
+  type?: unknown;
+  code?: unknown;
+  message?: unknown;
+  error?: { type?: unknown; code?: unknown; message?: unknown };
+  last_error?: { type?: unknown; code?: unknown; message?: unknown };
+  response?: {
+    error?: { type?: unknown; code?: unknown; message?: unknown };
+    incomplete_details?: { code?: unknown; message?: unknown; reason?: unknown };
+  };
+}
+
+// Bare error evidence is provisional: only a genuine terminal owns account-health status.
+const provisionalStatuses = new WeakMap<TerminalStatusContext, number>();
+const genuineTerminals = new WeakSet<TerminalStatusContext>();
+
+const UPSTREAM_DIAGNOSTIC_TOKEN = /^[A-Za-z0-9_.:-]{1,128}$/;
+
+function noteBoundedDiagnostic(
+  logCtx: TerminalStatusContext,
+  field: "upstreamErrorCode" | "upstreamErrorType" | "upstreamRequestId",
+  value: unknown,
+): void {
+  if (logCtx[field] !== undefined) return;
+  if (typeof value !== "string" || !UPSTREAM_DIAGNOSTIC_TOKEN.test(value)) return;
+  logCtx[field] = value;
+  const status = logCtx.terminalHttpStatus;
+  if (status === undefined || status >= 500) console.warn(`[opencodex] upstream failure${status ? ` status=${status}` : ""}${logCtx.upstreamErrorCode ? ` code=${logCtx.upstreamErrorCode}` : ""}${logCtx.upstreamRequestId ? ` request_id=${logCtx.upstreamRequestId}` : ""}`);
+}
+
+export function noteUpstreamRequestId(logCtx: TerminalStatusContext, headers: Headers): void {
+  noteBoundedDiagnostic(logCtx, "upstreamRequestId", headers.get("openai-request-id") ?? headers.get("x-request-id"));
+}
+
+export function captureUpstreamTerminalDiagnostics(logCtx: TerminalStatusContext, json: UpstreamErrorPayload): void {
+  captureTerminalHttpStatus(logCtx, json);
+  noteBoundedDiagnostic(logCtx, "upstreamErrorCode",
+    json.error?.code ?? json.last_error?.code ?? json.response?.error?.code ?? json.code);
+  noteBoundedDiagnostic(logCtx, "upstreamErrorType",
+    json.error?.type ?? json.last_error?.type ?? json.response?.error?.type);
+}
+
+export function upstreamDiagnosticLogFields(logCtx: UpstreamErrorDiagnostics): UpstreamErrorDiagnostics {
+  return {
+    ...(logCtx.upstreamErrorCode ? { upstreamErrorCode: logCtx.upstreamErrorCode } : {}),
+    ...(logCtx.upstreamErrorType ? { upstreamErrorType: logCtx.upstreamErrorType } : {}),
+    ...(logCtx.upstreamRequestId ? { upstreamRequestId: logCtx.upstreamRequestId } : {}),
+  };
+}
+
+function captureTerminalHttpStatus(
+  logCtx: TerminalStatusContext,
+  json: UpstreamErrorPayload,
+): void {
+  const type = json.type;
+  const terminal = type === "response.failed" || type === "response.completed" || type === "response.incomplete";
+  if (!terminal && type !== "error") return;
+  if (terminal && provisionalStatuses.has(logCtx)) {
+    const provisional = provisionalStatuses.get(logCtx);
+    provisionalStatuses.delete(logCtx);
+    if (logCtx.terminalHttpStatus === provisional) {
+      delete logCtx.terminalHttpStatus;
+      delete logCtx.terminalErrorCode;
+    }
+  }
+  if (logCtx.terminalHttpStatus !== undefined || (type === "error" && genuineTerminals.has(logCtx))) return;
+  if (terminal) genuineTerminals.add(logCtx);
+  const noteStatus = (status: number): void => {
+    logCtx.terminalHttpStatus = status;
+    if (type === "error") provisionalStatuses.set(logCtx, status);
+  };
+  // A completed terminal only retires provisional bare-error evidence; it records no status.
+  if (type === "response.completed") return;
+  const responseError = json.response?.error;
+  const responseDetails = json.response?.incomplete_details;
+  const candidates: Array<{ type?: unknown; code?: unknown; message?: unknown } | undefined> = [
+    json.error, json.last_error, responseError, responseDetails, json,
+  ];
+  const policy = candidates.some(candidate => (
+    candidate?.code === null || typeof candidate?.code === "string"
+  ) && isCyberPolicyCode(candidate.code as string | null | undefined))
+    || candidates.some(candidate => (
+      typeof candidate?.message === "string"
+      && candidate.message.trim().length > 0
+      && isCyberPolicyMessage(candidate.message)
+    ));
+  if (policy) {
+    logCtx.terminalErrorCode = CYBER_POLICY_ERROR_CODE;
+    noteStatus(400);
+    return;
+  }
+  // A quota terminal can carry only a structured reason, without an error message.
+  // Keep this separate from normal output limits and from the policy precedence above.
+  const quotaTag = (value: unknown): boolean => value === "usage_limit_reached"
+    || value === "rate_limit_exceeded" || value === "insufficient_quota";
+  const structuredRefusal = candidates.some(candidate => [400, 401, 403, 499].includes(
+    httpStatusFromTerminalError({
+      type: typeof candidate?.type === "string" ? candidate.type : undefined,
+      code: typeof candidate?.code === "string" ? candidate.code : undefined,
+    }),
+  ));
+  const ordinaryIncompleteReason = typeof responseDetails?.reason === "string"
+    && ["max_output_tokens", "content_filter", "steered", "upstream_stall_timeout", "adapter_eof"].includes(responseDetails.reason);
+  if (type === "response.incomplete" && !structuredRefusal && (quotaTag(responseDetails?.reason) || candidates.some(candidate =>
+    quotaTag(candidate?.code)
+    || quotaTag(candidate?.type) || candidate?.type === "rate_limit_error"
+    || (!ordinaryIncompleteReason && typeof candidate?.message === "string" && isRateLimitOrQuotaFailureMessage(candidate.message))
+  ))) {
+    // The shared quota classifier also accepts a numeric HTTP status as its message.
+    // Preserve explicit payment-required evidence rather than relabeling it as 429.
+    noteStatus(candidates.some(candidate => typeof candidate?.message === "string"
+      && Number(candidate.message.trim()) === 402) ? 402 : 429);
+    return;
+  }
+  if (type === "error") {
+    const structured = recognizedUpstreamError({
+      code: candidates.find(candidate => typeof candidate?.code === "string")?.code,
+      type: candidates.slice(0, -1).find(candidate => typeof candidate?.type === "string")?.type,
+    });
+    // Unrecognized bare errors leave the status to explicit event fields (combo preflight).
+    if (structured) noteStatus(structured.httpStatus);
+    return;
+  }
+  if (type !== "response.failed" || !responseError || typeof responseError !== "object") return;
+  const responseCode = responseError.code === null || typeof responseError.code === "string"
+    ? responseError.code
+    : undefined;
+  noteStatus(httpStatusFromTerminalError({
+    type: typeof responseError.type === "string" ? responseError.type : undefined,
+    code: responseCode,
+    message: typeof responseError.message === "string" ? responseError.message : undefined,
+  }));
+}