cartethyia 2.7.3 → 2.7.4

package/src/providers/provider-registry.ts

@@ -89,7 +89,7 @@ function assertAdapterIdentity(expected: ProviderId, adapter: ProviderAdapter):
   // error: `invalid_request` would blame the caller and invite a byte-identical
   // retry. `internal_error` (500) says what is true — the gateway is
   // misconfigured and the request never had a chance.
-  throw new GatewayError("internal_error", 500, "Loaded adapter ID does not match registration", {
+  throw new GatewayError("internal_error", 500, "Loaded adapter ID does not match registration (request {requestId}). Even we have bad days — check the registry wiring 🐻", {
     provider_id: expected,
     adapter_id: adapter.provider_id,
   });
@@ -122,12 +122,12 @@ export class ProviderRegistry {
   register(registration: ProviderRegistration): void {
     const providerId = parseProviderId(registration.provider_id);
     if (this.#registrations.has(providerId)) {
-      throw new GatewayError("invalid_request", 409, "Provider is already registered", {
+      throw new GatewayError("invalid_request", 409, "Provider is already registered (request {requestId}). This name's taken — pick another alias ✨", {
         provider_id: providerId,
       });
     }
     if (providerId !== registration.provider_id) {
-      throw new GatewayError("internal_error", 500, "Provider registration ID is not normalized", {
+      throw new GatewayError("internal_error", 500, "Provider registration ID is not normalized (request {requestId}). Even we have bad days — check the registry wiring 🐻", {
         provider_id: registration.provider_id,
       });
     }
@@ -158,7 +158,7 @@ export class ProviderRegistry {
   upsert(registration: ProviderRegistration): boolean {
     const providerId = parseProviderId(registration.provider_id);
     if (providerId !== registration.provider_id) {
-      throw new GatewayError("internal_error", 500, "Provider registration ID is not normalized", {
+      throw new GatewayError("internal_error", 500, "Provider registration ID is not normalized (request {requestId}). Even we have bad days — check the registry wiring 🐻", {
         provider_id: registration.provider_id,
       });
     }

package/src/providers/quota/quota-contracts.ts

@@ -58,20 +58,27 @@ export function totalRemainingCredit(
  * independent quota windows, or `null` when neither is reported.
  *
  * Pooled credits are summed before converting to percent, so one exhausted
- * bonus pack cannot hide balance in another. Independent windows keep their
- * own remaining percent and the lowest one gates the account.
+ * bonus pack cannot hide balance in another. A pooled window without a ceiling
+ * (Command Code credits) contributes its absolute remaining to the credit sum
+ * but cannot produce a percent, so it is not counted in the percent ratio.
+ * Independent windows keep their own remaining percent and the lowest one
+ * gates the account.
  */
 export function totalRemainingPercent(
   windows: readonly ProviderQuotaWindow[],
 ): number | null {
   let creditLimit = 0;
   let creditRemaining = 0;
+  let hasPooledLimit = false;
   let independentPercent: number | null = null;
   for (const window of windows) {
     if (window.accounting === "pooled") {
       const balance = creditWindowBalance(window);
       if (balance !== null) {
-        creditLimit += balance.limit;
+        if (balance.limit !== null) {
+          creditLimit += balance.limit;
+          hasPooledLimit = true;
+        }
         creditRemaining += balance.remaining;
       }
       continue;
@@ -85,8 +92,13 @@ export function totalRemainingPercent(
     independentPercent =
       independentPercent === null ? clamped : Math.min(independentPercent, clamped);
   }
-  const creditPercent =
-    creditLimit > 0 ? Math.min(100, Math.max(0, (creditRemaining / creditLimit) * 100)) : null;
+  // A pooled window with a reported ceiling (including a 0 ceiling — a spent
+  // balance) always defines a percent: 0 ceiling means 0% remaining.
+  const creditPercent = hasPooledLimit
+    ? creditLimit > 0
+      ? Math.min(100, Math.max(0, (creditRemaining / creditLimit) * 100))
+      : 0
+    : null;
   if (creditPercent === null) return independentPercent;
   if (independentPercent === null) return creditPercent;
   return Math.min(creditPercent, independentPercent);
@@ -94,20 +106,22 @@ export function totalRemainingPercent(
 
 function creditWindowBalance(
   window: ProviderQuotaWindow,
-): { readonly limit: number; readonly remaining: number } | null {
+): { readonly limit: number | null; readonly remaining: number } | null {
+  // A ceiling of 0 is a spent balance, not an absence of data; only a window
+  // with no remaining figure at all is skipped. `limit` may be null (Command
+  // Code reports credits without a ceiling) — the remaining total still counts.
   const limit =
-    typeof window.limit === "number" && Number.isFinite(window.limit) && window.limit > 0
+    typeof window.limit === "number" && Number.isFinite(window.limit) && window.limit >= 0
       ? window.limit
       : null;
-  if (limit === null) return null;
   let remaining: number | null = null;
   if (typeof window.remaining === "number" && Number.isFinite(window.remaining)) {
     remaining = window.remaining;
-  } else if (typeof window.used === "number" && Number.isFinite(window.used)) {
+  } else if (typeof window.used === "number" && Number.isFinite(window.used) && limit !== null) {
     remaining = limit - window.used;
   }
   if (remaining === null) return null;
-  return { limit, remaining: Math.min(limit, Math.max(0, remaining)) };
+  return { limit, remaining: Math.max(0, remaining) };
 }
 
 const TIMEOUT_MS = 15_000;

package/src/providers/quota/refresh.ts

@@ -16,7 +16,7 @@ import { type FetchLike, type ProviderQuotaResult } from "./quota-contracts";
 import type { ProviderId } from "../provider-contracts";
 import type { ProviderRegistry } from "../provider-registry";
 import { GLOBAL_QUOTA_LENS, setCachedQuota } from "./cache";
-import { record } from "../authentication/oauth-flow-store";
+import { asJsonbRecord } from "../../shared/coerce";
 
 /** Why an account quota refresh failed; `null` means the fetch succeeded. */
 export type QuotaRefreshFailureCode = "missing_credential" | "quota_fetch_failed";
@@ -355,7 +355,7 @@ async function runQuotaRefresh(
         ? (deps.markApiKeyCredential?.(target.providerId, credential) ?? credential)
         : credential;
     try {
-      const authState = record(target.authState);
+      const authState = asJsonbRecord(target.authState);
       quota = await fetchProviderQuota(deps.providerRegistry, target.providerId, marked, fetcher, {
         // Carried so a collector can reuse a reading captured from real
         // traffic rather than spending a request to rediscover it.

package/src/providers/search/search-provider.ts

@@ -53,7 +53,7 @@ function stringField(record: Record<string, unknown> | undefined, key: string):
 export function searchParamsFromBody(body: Record<string, unknown>): SearchParams {
   const query = typeof body.query === "string" ? body.query.trim() : "";
   if (query.length === 0)
-    throw new GatewayError("invalid_request", 400, "search query is required");
+    throw new GatewayError("invalid_request", 400, "search query is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   const rawMax = body.max_results;
   const maxResults =
     typeof rawMax === "number" && Number.isFinite(rawMax)
@@ -90,7 +90,7 @@ export function createSearchAdapter(spec: SearchProviderSpec): ProviderAdapter {
       throw new GatewayError(
         "capability_unsupported",
         400,
-        `${spec.provider_id} serves web search, not a chat wire`,
+        `${spec.provider_id} serves web search, not a chat wire (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
       );
     },
     async websearch(
@@ -113,7 +113,7 @@ export function createSearchAdapter(spec: SearchProviderSpec): ProviderAdapter {
         throw new GatewayError(
           "platform_unavailable",
           502,
-          `${spec.provider_id} search unreachable: ${error instanceof Error ? error.message : String(error)}`,
+          `${spec.provider_id} search unreachable (request {requestId}): ${error instanceof Error ? error.message : String(error)}. The connection ghosted us — come back in a moment 👻`,
         );
       }
       if (!res.ok) {
@@ -121,7 +121,7 @@ export function createSearchAdapter(spec: SearchProviderSpec): ProviderAdapter {
         throw new GatewayError(
           res.status >= 500 ? "platform_unavailable" : "invalid_request",
           res.status,
-          `${spec.provider_id} search error: ${detail.slice(0, 240)}`,
+          `${spec.provider_id} search error (request {requestId}): ${detail.slice(0, 240)}. The upstream came back empty-handed — retry 🌙`,
         );
       }
       const raw = await res.text();
@@ -135,7 +135,7 @@ export function createSearchAdapter(spec: SearchProviderSpec): ProviderAdapter {
         throw new GatewayError(
           "platform_unavailable",
           502,
-          `${spec.provider_id} search returned an unparseable body`,
+          `${spec.provider_id} search returned an unparseable body (request {requestId}). The upstream came back empty-handed — retry 🌙`,
         );
       }
       const results = spec.normalize(data);

package/src/security/abuse.ts

@@ -399,7 +399,7 @@ export class IpAbuseProtectionService {
     readonly signal?: AbortSignal;
   }): Promise<void> {
     if (input.signal?.aborted) {
-      throw new GatewayError("admission_unavailable", 503, "The abuse check never ran because the request was already cancelled.", {
+      throw new GatewayError("admission_unavailable", 503, "The abuse check never ran because the request was already cancelled (request {requestId}). Send it again whenever ready 🙃", {
         reason: "admission-unavailable",
       });
     }
@@ -436,7 +436,7 @@ export class IpAbuseProtectionService {
 
       if (outcome.banned) {
         metrics.cartethyia_ip_abuse_refusals_total.inc(1, { reason: "ip-banned" });
-        throw new GatewayError("quota_exceeded", 429, "This address is temporarily banned for too many failed requests. Wait for the ban to lift, then slow down.", {
+        throw new GatewayError("rate_limited", 429, "This address is temporarily banned for too many failed requests (request {requestId}). Wait for the ban to lift, then slow down. You've maxed this window — pace yourself ⏳", {
           // Distinguishes this from the rate-limited 429 below and from an API
           // key's own budget. It used to be "admission-unavailable", which is
           // the label for an *unreachable* store — so every refusal from this
@@ -454,7 +454,7 @@ export class IpAbuseProtectionService {
 
       if (outcome.count > this.maxRequestsPerWindow) {
         metrics.cartethyia_ip_abuse_refusals_total.inc(1, { reason: "ip-rate-limited" });
-        throw new GatewayError("quota_exceeded", 429, "This address is sending requests faster than the abuse limit allows. Back off and retry after the window rolls over.", {
+        throw new GatewayError("rate_limited", 429, "This address is sending requests faster than the abuse limit allows (request {requestId}). Back off and retry after the window rolls over. You've maxed this window — pace yourself ⏳", {
           reason: "ip-rate-limited",
           ip,
           route: input.route,
@@ -464,7 +464,7 @@ export class IpAbuseProtectionService {
       }
     } catch (err) {
       if (err instanceof GatewayError) throw err;
-      throw new GatewayError("admission_unavailable", 503, "The abuse-tracking store is unreachable, so requests from this address cannot be checked. Retry shortly.", {
+      throw new GatewayError("admission_unavailable", 503, "The abuse-tracking store is unreachable, so requests from this address cannot be checked (request {requestId}). Retry shortly. The bouncer stepped out — come back shortly 🚪", {
         reason: "admission-unavailable",
         cause: (err as Error).message,
       });

package/src/security/admission/reasons.ts

@@ -19,26 +19,26 @@ const REASON_META: Record<
   }
 > = {
   "rpm-exhausted": {
-    message: "This key has used its requests-per-minute allowance. Wait for the window to roll over, or raise the key's rpm limit.",
-    code: "quota_exceeded",
+    message: "This key has used its requests-per-minute allowance (request {requestId}). Wait for the window to roll over, or raise the key's rpm limit. You've maxed this window — pace yourself ⏳",
+    code: "rate_limited",
     status: 429,
     metricLabel: "rpm_exhausted",
   },
   "daily-token-limit": {
-    message: "This key has used today's token allowance. It resets at the start of the next day, or raise the key's daily limit.",
-    code: "quota_exceeded",
+    message: "This key has used today's token allowance (request {requestId}). It resets at the start of the next day, or raise the key's daily limit. Pace yourself — it resets tomorrow ⏳",
+    code: "rate_limited",
     status: 429,
     metricLabel: "daily",
   },
   "monthly-token-limit": {
-    message: "This key has used this month's token allowance. It resets at the start of the next month, or raise the key's monthly limit.",
-    code: "quota_exceeded",
+    message: "This key has used this month's token allowance (request {requestId}). It resets at the start of the next month, or raise the key's monthly limit. Saving up for next month? It resets then ⏳",
+    code: "rate_limited",
     status: 429,
     metricLabel: "monthly",
   },
   "lifetime-token-budget": {
-    message: "This key has spent its lifetime token budget. Raise the budget, or issue a new key.",
-    code: "quota_exceeded",
+    message: "This key has spent its lifetime token budget (request {requestId}). Raise the budget, or issue a new key. The piggy bank is empty — top it up or mint a new key 🐷",
+    code: "rate_limited",
     status: 429,
     metricLabel: "lifetime",
   },
@@ -47,27 +47,27 @@ const REASON_META: Record<
     // max-inflight. The two used to be indistinguishable and both named the
     // provider, sending operators to the wrong setting after a rejection. The
     // `details` carry the limit so a client can tell which one fired.
-    message: "This API key is already serving its maximum number of concurrent requests. Retry shortly, or raise the key's concurrency limit.",
+    message: "This API key is already serving its maximum number of concurrent requests (request {requestId}). Retry shortly, or raise the key's concurrency limit. It'll free up in a moment 🌊",
     code: "capacity_exhausted",
     status: 429,
     metricLabel: "concurrency",
   },
   "tenant-capacity-exhausted": {
-    message: "This tenant is already serving its maximum number of concurrent requests. Retry shortly, or raise the tenant's concurrency limit.",
+    message: "This tenant is already serving its maximum number of concurrent requests (request {requestId}). Retry shortly, or raise the tenant's concurrency limit. The tenant is maxed out right now — chill 🏠",
     code: "tenant_capacity_exhausted",
     status: 429,
     metricLabel: "tenant_capacity",
   },
   "model-not-allowed": {
-    message: "This key is not allowed to use this model under its allowlist. Add the model to the key, or use one it already allows.",
-    code: "model_not_found",
-    status: 404,
+    message: "This key is not allowed to use this model under its allowlist (request {requestId}). Add the model to the key, or use one it already allows. The door's locked for this one — check the allowlist 🔒",
+    code: "model_not_allowed",
+    status: 403,
     metricLabel: "model_not_allowed",
   },
   "model-denied": {
-    message: "This key's denylist blocks this model. Remove the model from the denylist, or use a different model.",
-    code: "model_not_found",
-    status: 404,
+    message: "This key's denylist blocks this model (request {requestId}). Remove the model from the denylist, or use a different model. This one's on the banned list — pick another 🚫",
+    code: "model_not_allowed",
+    status: 403,
     metricLabel: "model_not_allowed",
   },
   "admission-unavailable": {
@@ -76,7 +76,7 @@ const REASON_META: Record<
     // `invalid_counter`, `unknown_reservation`, `invalid_actual_usage`). The
     // second is not an outage, so the text must not claim one — it names the
     // effect the client can act on, and the diagnostic stays in `details.reason`.
-    message: "The gateway could not admit this request. Retry shortly; if it persists, check the instance's Redis or coordination backend.",
+    message: "The gateway could not admit this request (request {requestId}). Retry shortly; if it persists, check the instance's Redis or coordination backend. The bouncer stepped out — come back shortly 🚪",
     code: "admission_unavailable",
     status: 503,
     metricLabel: "admission_unavailable",

package/src/security/api-key-auth.ts

@@ -239,7 +239,7 @@ export interface ResolvedApiKey {
  * indistinguishable — distinguishing them would let a caller confirm that a
  * guessed token once existed — so there is no variant carrying a reason.
  */
-const INVALID_KEY_MESSAGE = "Invalid API key. Check the key you are sending, or create a new one in API Keys and send it as: Authorization: Bearer <key>.";
+const INVALID_KEY_MESSAGE = "Invalid API key (request {requestId}). Check the key you are sending, or create a new one in API Keys and send it as: Authorization: Bearer <key>. Wrong key, right door — double-check and come back 🔑";
 
 export function unknownApiKeyError(): GatewayError {
   return new GatewayError("authentication_failed", 401, INVALID_KEY_MESSAGE);
@@ -258,7 +258,7 @@ export function modelsListApiKeyError(): GatewayError {
   return new GatewayError(
     "authentication_failed",
     401,
-    "Invalid API key. Rotate the default Cartethyia API key in API Keys and send the new key as: Authorization: Bearer <key>.",
+    "Invalid API key (request {requestId}). Rotate the default Cartethyia API key in API Keys and send the new key as: Authorization: Bearer <key>. Wrong key, right door — rotate and try again 🔑",
   );
 }
 
@@ -279,12 +279,12 @@ export function requestToken(headers: Headers | Record<string, string>): string
     // *different* credentials stay a conflict — accepting whichever came first
     // would silently decide the request's identity.
     if (bearerMatch?.[1] === apiKey) return apiKey;
-    throw new GatewayError("invalid_request", 400, "The request sends two different credentials. Send exactly one key, either as Authorization: Bearer <key> or as the api-key header.");
+    throw new GatewayError("invalid_request", 400, "The request sends two different credentials (request {requestId}). Send exactly one key, either as Authorization: Bearer <key> or as the api-key header. Pick one key and stick with it 🤝");
   }
   if (hasApiKey) return apiKey;
   const token = bearerMatch?.[1];
   if (token === undefined)
-    throw new GatewayError("invalid_request", 401, "The request carries no usable credential. Send the key as: Authorization: Bearer <key>.");
+    throw new GatewayError("authentication_failed", 401, "The request carries no usable credential (request {requestId}). Send the key as: Authorization: Bearer <key>. We need a key to let you in 🔑");
   return token;
 }
 

package/src/shared/coerce.ts

@@ -13,6 +13,25 @@ export function asRecord(value: unknown): Record<string, unknown> | undefined {
     : undefined;
 }
 
+/**
+ * Narrow a stored `auth_state`/JSONB value to a plain object. Postgres'
+ * drizzle `jsonb` arrives as a POJO; SQLite's text-backed column arrives as
+ * a JSON STRING. Parse the string form so both backends hand downstream
+ * readers the same shape — otherwise auth-state-dependent providers (Qoder's
+ * userId/machineId, Trae's region, …) silently lose their identity on the
+ * SQLite backend.
+ */
+export function asJsonbRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value === "string") {
+    try {
+      return asRecord(JSON.parse(value));
+    } catch {
+      return undefined;
+    }
+  }
+  return asRecord(value);
+}
+
 /** Narrow to a finite number, else `undefined`. `NaN`/`Infinity` are not numbers here. */
 export function asNumber(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;

package/src/transport/dispatch/attempt-finalize.ts

@@ -425,7 +425,7 @@ export function terminalFailure(
     return new GatewayError(
       "transport_unavailable",
       502,
-      "The upstream closed the response without reporting a result. Retry; if it keeps happening, the account or pool is unstable.",
+      "The upstream closed the response without reporting a result (request {requestId}). Retry; if it keeps happening, the account or pool is unstable. The connection ghosted us — come back in a moment 👻",
       {},
       "upstream",
     );
@@ -437,7 +437,7 @@ export function terminalFailure(
     const details: Record<string, unknown> = {};
     if (terminal.provider_stop_reason) details["provider_code"] = terminal.provider_stop_reason;
     if (terminal.stop_details) Object.assign(details, terminal.stop_details);
-    const message = typeof details["message"] === "string" ? details["message"] : "upstream request failed";
+    const message = typeof details["message"] === "string" ? details["message"] : "upstream request failed (request {requestId}). The upstream came back empty-handed — retry 🌙";
    // Preserve the upstream's error code when the provider embedded it in
    // `stop_details` (Cursor writes `quota_exceeded` and `authentication_failed`
    // there). Wrapping every terminal failure as `transport_unavailable` discarded
@@ -460,7 +460,7 @@ export function terminalFailure(
     // reports it as truncation instead.
     return options.truncated === true
       ? undefined
-      : new GatewayError("transport_closed", 499, "request was cancelled");
+      : new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");
   }
   return undefined;
 }
@@ -823,6 +823,7 @@ export async function completeAttempt(
           (completion.error instanceof ProxyConnectRefusalError ? "network" : undefined);
         await recordPoolDispatchOutcome(completion.db, completion.networkPoolId, {
           succeeded: completion.status === "completed",
+          ...(completion.providerId === undefined ? {} : { providerId: completion.providerId }),
           ...(completion.error === undefined ? {} : { error: completion.error }),
           // A CONNECT refusal is the proxy's own answer, given before any
           // upstream was dialed, so it is a network fault even though the

package/src/transport/dispatch/attempt-loop.ts

@@ -41,7 +41,8 @@ import {
   type ProviderExchangeCapture,
 } from "./attempt-finalize";
 import { repriceUsage } from "../../providers/provider-usage";
-import { isFreeTierIpBlock, isOAuthCredentialInvalidated, shouldCooldownPool } from "./retry-policy";
+import { classifyEgressFailure } from "../../network/rate-limit-verdict";
+import { isOAuthCredentialInvalidated } from "./retry-policy";
 import { drainAbortReason } from "../shutdown-notice";
 
 /**
@@ -316,7 +317,7 @@ export async function runAttemptLoop<TResult, TAdapter>(
     };
     try {
       if (state.abortController.signal.aborted)
-        throw new GatewayError("transport_closed", 499, "request was cancelled");
+        throw new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");
       const { credential, adapter } = await input.prepare(candidate);
       const host = input.resolveHost?.(candidate);
       // Single attempt-lease manager owns acquisition order (admission →
@@ -353,9 +354,10 @@ export async function runAttemptLoop<TResult, TAdapter>(
       });
     } catch (error) {
       // A drain aborts the controller, so a mid-flight attempt unwinds here as
-      // an abort. Surface the typed shutdown error (503 shutting_down /
-      // restart_for_update) instead of an opaque `transport_closed`, so the
-      // client's JSON error — not just the SSE path — names the real cause.
+      // an abort. Surface the typed shutdown error (503 shutting_down, reason
+      // restart_for_update for an update drain) instead of an opaque
+      // `transport_closed`, so the client's JSON error — not just the SSE path —
+      // names the real cause.
       const drain = drainAbortReason(state.abortController.signal.reason);
       if (drain !== undefined) error = drain;
       lastError = error;
@@ -374,11 +376,12 @@ export async function runAttemptLoop<TResult, TAdapter>(
       // single candidate carrying every pool). Judging it there is what made a
       // refused egress end the request instead of failing over to a healthy
       // one.
-      const rateLimitedPool = !cancelled && shouldCooldownPool(error, candidate.provider_id);
+      const egressVerdict = !cancelled ? classifyEgressFailure(error, candidate.provider_id) : { kind: "none" } as const;
       // A free-tier refusal is only ever this provider's: the guard is gated on
       // `ipScopedRateLimit` in the provider metadata, so a 403 from any other
       // upstream still means what it always did and never retires an egress.
-      const blockedPool = !cancelled && isFreeTierIpBlock(error, candidate.provider_id);
+      const rateLimitedPool = egressVerdict.kind === "cooldown";
+      const blockedPool = egressVerdict.kind === "blocked";
       const poolScopedFailure =
         (rateLimitedPool || blockedPool) &&
         networkPoolId !== undefined &&

package/src/transport/dispatch/empty-stream.ts

@@ -107,7 +107,7 @@ export async function fetchWithEmptyStreamRecovery(
   const sleep = deps.policy?.sleep ?? abortableSleep;
 
   if (endpoints.length === 0) {
-    throw new GatewayError("platform_unavailable", 502, "No endpoints available", {}, "upstream");
+    throw new GatewayError("platform_unavailable", 502, "No endpoints available (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
   }
 
   for (let endpointIndex = 0; endpointIndex < endpoints.length; endpointIndex++) {
@@ -118,7 +118,7 @@ export async function fetchWithEmptyStreamRecovery(
     for (let replay = 0; replay <= replaysAllowed; replay++) {
       // Check abort before each fetch
       if (deps.signal.aborted) {
-        throw new GatewayError("transport_closed", 499, "Aborted");
+        throw new GatewayError("transport_closed", 499, "The request was aborted (request {requestId}). Send it again whenever ready 🙃");
       }
 
       // Check deadline floor
@@ -128,7 +128,7 @@ export async function fetchWithEmptyStreamRecovery(
         throw new GatewayError(
           "platform_unavailable",
           502,
-          "Deadline exhausted before empty-stream replay",
+          "Deadline exhausted before empty-stream replay (request {requestId}). Some things just take longer 🐢",
           {},
           "upstream",
         );
@@ -181,7 +181,7 @@ export async function fetchWithEmptyStreamRecovery(
   throw new GatewayError(
     "platform_unavailable",
     502,
-    "All endpoints returned empty streams",
+    "All endpoints returned empty streams (request {requestId}). The upstream came back empty-handed — retry 🌙",
     {},
     "upstream",
   );
@@ -204,11 +204,11 @@ async function fetchWithTimeout(
       // It must surface as a deadline failure, never as a `transport_closed`
       // 499 — that code is reserved for genuine client cancellations and would
       // otherwise hide a real upstream wait behind "cancelled by client".
-      reject(new GatewayError("deadline_exceeded", 504, "First event timeout", {}, "upstream"));
+      reject(new GatewayError("deadline_exceeded", 504, "First event timeout (request {requestId}). Some things just take longer 🐢", {}, "upstream"));
     }, timeoutMs);
     signal.addEventListener("abort", () => {
       clearTimeout(timer);
-      reject(new GatewayError("transport_closed", 499, "Aborted"));
+      reject(new GatewayError("transport_closed", 499, "The request was aborted (request {requestId}). Send it again whenever ready 🙃"));
     }, { once: true });
   });
 

package/src/transport/dispatch/generation.ts

@@ -163,18 +163,18 @@ export function createNativeSurfaceHandler(
       throw new GatewayError(
         "invalid_request",
         400,
-        `The ${noun} body must be a JSON object. Send one with at least a model and a prompt.`,
+        `The ${noun} body must be a JSON object (request {requestId}). Send one with at least a model and a prompt. Check the shape of what you sent — then resend 🪞`,
       );
     }
     const generation = body as Record<string, unknown>;
     if (typeof generation.model !== "string" || generation.model.trim().length === 0) {
-      throw new GatewayError("invalid_request", 400, `A model is required: it names the ${noun} provider to use.`);
+      throw new GatewayError("invalid_request", 400, `A model is required (request {requestId}): it names the ${noun} provider to use. Check the shape of what you sent — then resend 🪞`);
     }
     if (!authorization.snapshot.scopes?.includes("routing:invoke" as never)) {
       throw new GatewayError(
-        "invalid_request",
+        "policy_rejected",
         403,
-        `${noun} generation not allowed for this key — enable routing:invoke on the API key`,
+        `${noun} generation not allowed for this key (request {requestId}) — enable routing:invoke on the API key. Not allowed by policy — no hard feelings 🫂`,
       );
     }
     // Trust boundary only. Keep accepting `messages` for chat-backed providers
@@ -183,7 +183,7 @@ export function createNativeSurfaceHandler(
       const hasPrompt = typeof generation.prompt === "string" && generation.prompt.trim().length > 0;
       const hasMessages = Array.isArray(generation.messages) && generation.messages.length > 0;
       if (!hasPrompt && !hasMessages) {
-        throw new GatewayError("invalid_request", 400, "prompt is required");
+        throw new GatewayError("invalid_request", 400, "prompt is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
       }
       if (generation.n !== undefined) {
         const n = generation.n;
@@ -191,7 +191,7 @@ export function createNativeSurfaceHandler(
           throw new GatewayError(
             "invalid_request",
             400,
-            `n must be an integer between 1 and ${MAX_ITEMS_PER_REQUEST}`,
+            `n must be an integer between 1 and ${MAX_ITEMS_PER_REQUEST} (request {requestId}). Check the shape of what you sent — then resend 🪞`,
           );
         }
       }
@@ -219,7 +219,7 @@ export function createNativeSurfaceHandler(
       candidates: prepared.candidates,
       tenantId: prepared.authorization.tenantId,
       strictPoolSelection: false,
-      exhaustedError: new GatewayError("admission_unavailable", 503, `no eligible ${noun} generation route`),
+      exhaustedError: new GatewayError("route_unavailable", 503, `no eligible ${noun} generation route (request {requestId}). The bouncer stepped out — come back shortly 🚪`),
       prepare: async (candidate) => {
         const credential = candidate.provider_account_id
           ? await resolveCredentialForAccount(
@@ -239,7 +239,7 @@ export function createNativeSurfaceHandler(
           throw new GatewayError(
             "capability_unsupported",
             400,
-            `${noun} generation is unavailable for this provider`,
+            `${noun} generation is unavailable for this provider (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
           );
         }
         return { credential, adapter };
@@ -344,7 +344,7 @@ export function createNativeSurfaceHandler(
                   new GatewayError(
                     "capability_unsupported",
                     400,
-                    `${noun} generation is unavailable for this provider`,
+                    `${noun} generation is unavailable for this provider (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
                   ),
                 )
               : adapter

package/src/transport/dispatch/leases.ts

@@ -141,7 +141,7 @@ async function acquirePoolSlot(
       throw new GatewayError(
         "proxy_pool_unhealthy",
         503,
-        "Every proxy pool this route requires is unhealthy or disabled. Repair a pool, or relax the route's pool requirement.",
+        "Every proxy pool this route requires is unhealthy or disabled (request {requestId}). Repair a pool, or relax the route's pool requirement. This bridge looks shaky — repair or reroute 🔧",
         { reason: "no_healthy_pool" },
         "network",
       );
@@ -172,7 +172,7 @@ async function acquirePoolSlot(
     throw new GatewayError(
       "proxy_pool_unavailable",
       503,
-      "No active proxy pool is available because coordination is unavailable.",
+      "No active proxy pool is available because coordination is unavailable (request {requestId}). The bouncer stepped out — come back shortly 🚪",
       { reason: "coordination_unavailable" },
       "network",
     );
@@ -219,14 +219,14 @@ async function acquirePoolSlot(
     failure.reason === "at_capacity" || failure.reason === "provider_at_capacity" ? 429 : 503;
   const message =
     failure.reason === "at_capacity"
-      ? "Every proxy pool for this provider is at its concurrency limit. Retry shortly, or add a pool or raise its capacity."
+      ? "Every proxy pool for this provider is at its concurrency limit (request {requestId}). Retry shortly, or add a pool or raise its capacity. The pools are full right now — chill 🌊"
       : failure.reason === "provider_at_capacity"
-        ? "Every proxy pool has reached this provider's per-proxy concurrency limit. Retry shortly, raise the limit in the provider's routing settings, or add a pool."
+        ? "Every proxy pool has reached this provider's per-proxy concurrency limit (request {requestId}). Retry shortly, raise the limit in the provider's routing settings, or add a pool. The proxies are working overtime — hang tight ⚡️"
         : failure.reason === "blocked"
-          ? "All proxy pools are saturated for this provider: the upstream refuses every egress configured for it. Replace a blocked proxy, or add one the upstream has not flagged."
+          ? "All proxy pools are saturated for this provider (request {requestId}): the upstream refuses every egress configured for it. Replace a blocked proxy, or add one the upstream has not flagged. All roads blocked — time to find a new route 🗺️"
           : failure.reason === "cooldown"
-            ? "Every proxy pool for this provider is cooling down after upstream failures. Retry once the cooldown resets."
-            : "No active proxy pool is configured for this tenant and provider. Add one, or route this provider through direct egress.";
+            ? "Every proxy pool for this provider is cooling down after upstream failures (request {requestId}). Retry once the cooldown resets. The proxies are catching their breath — zzz 💤"
+            : "No active proxy pool is configured for this tenant and provider (request {requestId}). Add one, or route this provider through direct egress. No bridge to cross — configure a pool first 🏗️";
   throw new GatewayError(code, status, message, {
     pools: failure.pools,
     // Only measured evidence: a cooldown's real reset instant. The
@@ -279,7 +279,7 @@ export async function acquireAttemptLeases(
       : await acquirePoolSlot(candidate, source, input.poolSelector, input.strictPoolSelection);
     if (slot) partial.proxySlot = slot;
     if (input.strictPoolSelection && input.signal.aborted)
-      throw new GatewayError("transport_closed", 499, "request was cancelled");
+      throw new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");
     partial.reservation = await source.routingEngine.reserve({
       ...source.plan,
       candidates: [candidate],