cartethyia 2.7.3 → 2.7.5

package/src/transport/dispatch/systemone.ts

@@ -1,11 +1,15 @@
 import type { ProviderAdapter, ProviderDispatchTarget } from "../../providers/provider-contracts";
 import { GatewayError } from "../../protocol/gateway-error";
-import { resolveCredentialForAccount } from "../../providers/operations/provider-credential-service";
 import { metrics } from "../../observability/metrics";
-import { parseThinkingSuffix } from "../../protocol/translation/thinking";
-import { completeAttempt, estimatedUsage, nativeCompletionBase } from "./attempt-finalize";
-import { repriceUsage, usageFromProvider } from "../../providers/provider-usage";
+import { estimatedUsage, nativeCompletionBase, completeAttempt } from "./attempt-finalize";
 import { runAttemptLoop } from "./attempt-loop";
+import {
+  networkFetchContext,
+  requireRecordBody,
+  resolveAttemptCredential,
+  stripThinkingSuffix,
+  usageFromUpstreamClone,
+} from "./native-shared";
 
 /**
  * The native System One route (`POST /v1/systemone`) and the dependency surface
@@ -20,7 +24,7 @@ import { runAttemptLoop } from "./attempt-loop";
  */
 import type { GatewayHandlerDeps } from "./handler-deps";
 
-export type SystemoneHandlerDeps = GatewayHandlerDeps;
+type SystemoneHandlerDeps = GatewayHandlerDeps;
 
 /** Adapter that can serve a System One decision request. */
 type SystemoneAdapter = ProviderAdapter & {
@@ -31,36 +35,34 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
   return async ({ request }: { request: Request }): Promise<Response> => {
     const state = deps.stateStore.require(request);
     const authorization = state.authorization;
-    const body = state.ingressBody;
-    if (!authorization || body === null || typeof body !== "object" || Array.isArray(body))
-      throw new GatewayError("invalid_request", 400, "systemone request body must be a JSON object");
-    const decision = body as Record<string, unknown>;
+    const decision = requireRecordBody(
+      state,
+      "systemone request body must be a JSON object (request {requestId}). Check the shape of what you sent — then resend 🪞",
+    );
     if (typeof decision.model !== "string" || decision.model.trim().length === 0)
-      throw new GatewayError("invalid_request", 400, "model is required");
+      throw new GatewayError("invalid_request", 400, "model is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
     // A thinking suffix (`model(high)`) is stripped for the same reason the
     // canonical preparer strips it: the route matches the model name against the
     // allowlist and the route plan, and `(high)` is not part of any registered
     // id. The level itself is dropped — a decision request carries no reasoning
     // effort to shape, and the body is passed upstream verbatim.
-    const { model: bareModel } = parseThinkingSuffix(decision.model);
-    const decisionBody: Record<string, unknown> =
-      bareModel === decision.model ? decision : { ...decision, model: bareModel };
+    const { bareModel, body: decisionBody } = stripThinkingSuffix(decision.model, decision);
     // Trust boundary only: the decision model's own question shapes are
     // upstream's to validate. `state` and a `questions` object are what make a
     // System One request a System One request at all.
     if (decision.state === undefined || decision.state === null)
-      throw new GatewayError("invalid_request", 400, "state is required");
+      throw new GatewayError("invalid_request", 400, "state is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
     if (
       decision.questions === undefined ||
       decision.questions === null ||
       typeof decision.questions !== "object" ||
       Array.isArray(decision.questions)
     )
-      throw new GatewayError("invalid_request", 400, "questions must be an object");
+      throw new GatewayError("invalid_request", 400, "questions must be an object (request {requestId}). Check the shape of what you sent — then resend 🪞");
     const prepared = await deps.proxyPreparer.prepareNativeService({
       model: bareModel,
       serviceKind: "systemone",
-      authorization,
+      authorization: authorization!,
       ...(state.abortController.signal ? { signal: state.abortController.signal } : {}),
       ...(state.clientUserAgent === undefined ? {} : { clientUserAgent: state.clientUserAgent }),
     });
@@ -80,30 +82,18 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
       // Lenient pool semantics: a missing slot tolerates direct egress.
       strictPoolSelection: false,
       exhaustedError: new GatewayError(
-        "admission_unavailable",
+        "route_unavailable",
         503,
-        "no eligible System One route",
+        "no eligible System One route (request {requestId}). The bouncer stepped out — come back shortly 🚪",
       ),
       prepare: async (candidate) => {
-        const credential = candidate.provider_account_id
-          ? await resolveCredentialForAccount(
-              deps.db,
-              candidate.provider_id,
-              candidate.provider_account_id,
-              deps.oauthRefreshService && deps.resolveOAuthRefresher
-                ? { refreshService: deps.oauthRefreshService, resolveRefresher: deps.resolveOAuthRefresher }
-                : undefined,
-            )
-          : {
-              provider_id: candidate.provider_id as ProviderAdapter["provider_id"],
-              credential_kind: "none" as const,
-            };
+        const credential = await resolveAttemptCredential(deps, candidate);
         const adapter = (await deps.resolveProviderAdapter?.(candidate.provider_id)) as SystemoneAdapter | undefined;
         if (!adapter || typeof adapter.systemone !== "function")
           throw new GatewayError(
             "capability_unsupported",
             400,
-            "System One transport unavailable for this provider",
+            "System One transport unavailable for this provider (request {requestId}). Know your tools — this one just isn't in the box 🧰",
           );
         return { credential, adapter };
       },
@@ -131,14 +121,7 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
           deadline: state.deadlineMs,
           abort_signal: state.abortController.signal,
           ...(candidate.user_agent === undefined ? {} : { user_agent: candidate.user_agent }),
-          ...(deps.networkBindingFactory
-            ? {
-                outbound_fetch: deps.networkBindingFactory.fetch(
-                  leases.proxySlot?.poolId,
-                  authorization.tenantId,
-                ),
-              }
-            : {}),
+          ...networkFetchContext(deps, leases.proxySlot?.poolId, authorization!.tenantId),
         });
         if (!response.ok) {
           // Surface the upstream decision error verbatim: it is the operator's
@@ -148,26 +131,15 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
           throw new GatewayError(
             response.status >= 500 ? "platform_unavailable" : "invalid_request",
             response.status,
-            `System One upstream error: ${detail.slice(0, 240)}`,
+            `System One upstream error (request {requestId}): ${detail.slice(0, 240)}`,
           );
         }
         // Prefer the usage the decision endpoint reported; fall back to the
         // fixed native estimate. `response.clone()` leaves the body readable
         // for the client.
-        let reportedUsage: ReturnType<typeof usageFromProvider>;
-        try {
-          const parsed: unknown = await response.clone().json();
-          reportedUsage = usageFromProvider(
-            typeof parsed === "object" && parsed !== null
-              ? (parsed as Record<string, unknown>)["usage"]
-              : undefined,
-          );
-        } catch {
-          reportedUsage = undefined;
-        }
-        const usage = repriceUsage(
-          reportedUsage ??
-            estimatedUsage(prepared.estimatedInputTokens, prepared.estimatedOutputTokens),
+        const usage = await usageFromUpstreamClone(
+          response,
+          estimatedUsage(prepared.estimatedInputTokens, prepared.estimatedOutputTokens),
           candidate.provider_id,
           candidate.model_id,
         );

package/src/transport/dispatch/token-count.ts

@@ -36,46 +36,48 @@
 import type { ProviderAdapter, ProviderDispatchTarget } from "../../providers/provider-contracts";
 import { GatewayError } from "../../protocol/gateway-error";
 import { isRecord } from "../../protocol/codecs";
-import { resolveCredentialForAccount } from "../../providers/operations/provider-credential-service";
 import { metrics } from "../../observability/metrics";
+import type { TelemetryBatchBuffer } from "../../observability/telemetry-buffer";
 import type { ProxyRequestState } from "../request/state";
 import type { PreparedNativeRequest } from "../request/preparer";
 import { completeAttempt, estimatedUsage, nativeCompletionBase } from "./attempt-finalize";
+import { finalizeRequestTelemetry } from "../guards/error-lifecycle";
 import { runAttemptLoop } from "./attempt-loop";
+import { hasScope, networkFetchContext, requireRecordBody, resolveAttemptCredential } from "./native-shared";
 
 import type { GatewayHandlerDeps } from "./handler-deps";
 
-export type TokenCountHandlerDeps = GatewayHandlerDeps;
+type TokenCountHandlerDeps = GatewayHandlerDeps;
 
 /** Builds the `POST /v1/messages/count_tokens` handler. */
 export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
   return async ({ request }: { request: Request }): Promise<Response> => {
     const state = deps.stateStore.require(request);
     const authorization = state.authorization;
-    const body = state.ingressBody;
-    if (!authorization || body === null || typeof body !== "object" || Array.isArray(body)) {
-      throw new GatewayError(
-        "invalid_request",
-        400,
-        "The count_tokens body must be a JSON object, the same shape POST /v1/messages accepts.",
-      );
+    const countBody = requireRecordBody(
+      state,
+      "The count_tokens body must be a JSON object (request {requestId}), the same shape POST /v1/messages accepts. Check the shape of what you sent — then resend 🪞",
+    );
+    // `requireRecordBody` already refused a missing authorization; this guard
+    // exists only to narrow the type for the code below.
+    if (!authorization) {
+      throw new GatewayError("invalid_request", 400, "authentication required (request {requestId})");
     }
-    const countBody = body as Record<string, unknown>;
 
     // `model` names the route and `messages` is what gets counted; both are the
     // upstream's own required fields, so the gateway does not restate its own
     // narrower rule and risk rejecting a body the provider would accept.
     if (typeof countBody.model !== "string" || countBody.model.trim().length === 0) {
-      throw new GatewayError("invalid_request", 400, "A model is required: it names the provider to count with.");
+      throw new GatewayError("invalid_request", 400, "A model is required (request {requestId}): it names the provider to count with. Check the shape of what you sent — then resend 🪞");
     }
     if (!Array.isArray(countBody.messages)) {
-      throw new GatewayError("invalid_request", 400, "messages must be an array — there is nothing to count without it.");
+      throw new GatewayError("invalid_request", 400, "messages must be an array (request {requestId}) — there is nothing to count without it. Check the shape of what you sent — then resend 🪞");
     }
-    if (!authorization.snapshot.scopes?.includes("routing:invoke" as never)) {
+    if (!hasScope(authorization?.snapshot.scopes, "routing:invoke")) {
       throw new GatewayError(
-        "invalid_request",
+        "policy_rejected",
         403,
-        "token counting not allowed for this key — enable routing:invoke on the API key",
+        "token counting not allowed for this key (request {requestId}) — enable routing:invoke on the API key. Not allowed by policy — no hard feelings 🫂",
       );
     }
 
@@ -93,7 +95,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
       // real 429/503 — a fabricated count would tell the client its context
       // fits when nothing is there to serve the turn that follows.
       if (!(error instanceof GatewayError) || error.code !== "capability_unsupported") throw error;
-      return estimatedCountResponse(state, countBody);
+      return estimatedCountResponse(state, countBody, deps.telemetryBuffer, deps.db);
     }
 
     return runAttemptLoop<Response, ProviderAdapter>({
@@ -111,27 +113,15 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
       tenantId: prepared.authorization.tenantId,
       strictPoolSelection: false,
       exhaustedError: new GatewayError(
-        "admission_unavailable",
+        "route_unavailable",
         503,
-        "no eligible route can count tokens for this model",
+        "no eligible route can count tokens for this model (request {requestId}). The bouncer stepped out — come back shortly 🚪",
       ),
       prepare: async (candidate) => {
-        const credential = candidate.provider_account_id
-          ? await resolveCredentialForAccount(
-              deps.db,
-              candidate.provider_id,
-              candidate.provider_account_id,
-              deps.oauthRefreshService && deps.resolveOAuthRefresher
-                ? { refreshService: deps.oauthRefreshService, resolveRefresher: deps.resolveOAuthRefresher }
-                : undefined,
-            )
-          : {
-              provider_id: candidate.provider_id as ProviderAdapter["provider_id"],
-              credential_kind: "none" as const,
-            };
+        const credential = await resolveAttemptCredential(deps, candidate);
         const adapter = await deps.resolveProviderAdapter?.(candidate.provider_id);
         if (!adapter) {
-          throw new GatewayError("capability_unsupported", 400, "token counting is unavailable for this provider");
+          throw new GatewayError("capability_unsupported", 400, "token counting is unavailable for this provider (request {requestId}). Know your tools — this one just isn't in the box 🧰");
         }
         return { credential, adapter };
       },
@@ -146,7 +136,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
 
         const adapter = context.adapter;
         if (typeof adapter.dispatchNativeService !== "function") {
-          throw new GatewayError("capability_unsupported", 400, "token counting is unavailable for this provider");
+          throw new GatewayError("capability_unsupported", 400, "token counting is unavailable for this provider (request {requestId}). Know your tools — this one just isn't in the box 🧰");
         }
 
         const target: ProviderDispatchTarget = {
@@ -167,14 +157,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
           deadline: state.deadlineMs,
           abort_signal: state.abortController.signal,
           ...(candidate.user_agent === undefined ? {} : { user_agent: candidate.user_agent }),
-          ...(deps.networkBindingFactory
-            ? {
-                outbound_fetch: deps.networkBindingFactory.fetch(
-                  leases.proxySlot?.poolId,
-                  authorization.tenantId,
-                ),
-              }
-            : {}),
+          ...networkFetchContext(deps, leases.proxySlot?.poolId, authorization.tenantId),
         });
 
         // A count is free and generates nothing, so nothing is reserved or
@@ -221,20 +204,40 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
  *
  * No attempt is finalized: nothing was leased, nothing was sent upstream, and
  * no provider produced this number, so recording it against an account would
- * invent usage the account never served. The request still gets an outcome —
- * without one the `afterResponse` hook finalizes it as a failure, and a count
- * that answered 200 would show up in Console Log as an error.
+ * invent usage the account never served. The request is still finalized through
+ * `finalizeRequestTelemetry` (the early-rejection pattern) — without it the
+ * latency histogram, the `request_complete` console event, and the durable
+ * telemetry row all miss this request — and `state.completed` prevents the
+ * `afterResponse` fallback from finalizing it a second time.
  */
 function estimatedCountResponse(
   state: ProxyRequestState,
   countBody: Record<string, unknown>,
+  telemetryBuffer: TelemetryBatchBuffer | undefined,
+  db: GatewayHandlerDeps["db"],
 ): Response {
   const inputTokens = estimateMessagesInputTokens(countBody);
   const payload = JSON.stringify({ input_tokens: inputTokens });
-  state.outcome = { status: "completed", httpStatus: 200 };
+  // The request still gets an outcome — without one the `afterResponse` hook
+  // would finalize it as a failure, and a count that answered 200 would show up
+  // in Console Log as an error. `usage` is a zero-priced estimate: nothing was
+  // leased and no provider produced this number, so recording a cost against an
+  // account would invent usage the account never served (`estimated_cost: null`).
+  state.outcome = {
+    status: "completed",
+    httpStatus: 200,
+    usage: estimatedUsage(inputTokens, 0),
+  };
   state.completed = true;
   state.clientResponseText = payload;
   metrics.proxy_requests_total.inc(1, { status: "completed" });
+  // Finalize telemetry inline (the early-rejection pattern) instead of routing
+  // through `completeAttempt`: there was no lease and no provider — but the
+  // latency histogram, the `request_complete` console event, and the durable
+  // row must still happen, exactly once. `completed = true` also disables the
+  // `afterResponse` fallback, which is what used to make this request vanish
+  // from telemetry entirely.
+  if (telemetryBuffer) finalizeRequestTelemetry(state, telemetryBuffer, db);
   return new Response(payload, {
     headers: {
       "content-type": "application/json",
@@ -255,7 +258,7 @@ function estimatedCountResponse(
  * `/v1/messages?beta=true/count_tokens` — the counting segment lands inside the
  * query, so the upstream sees the chat path with junk after it and never counts.
  */
-export function joinCountTokensPath(endpoint: string): string {
+function joinCountTokensPath(endpoint: string): string {
   const queryAt = endpoint.indexOf("?");
   const path = queryAt === -1 ? endpoint : endpoint.slice(0, queryAt);
   const query = queryAt === -1 ? "" : endpoint.slice(queryAt);

package/src/transport/dispatch/websearch.ts

@@ -16,57 +16,50 @@
  */
 import type { ProviderAdapter, ProviderDispatchTarget } from "../../providers/provider-contracts";
 import { GatewayError } from "../../protocol/gateway-error";
-import { resolveCredentialForAccount } from "../../providers/operations/provider-credential-service";
 import { metrics } from "../../observability/metrics";
-import { parseThinkingSuffix } from "../../protocol/translation/thinking";
 import { completeAttempt, estimatedUsage, nativeCompletionBase } from "./attempt-finalize";
 import { runAttemptLoop } from "./attempt-loop";
+import {
+  hasScope,
+  jsonResponse,
+  networkFetchContext,
+  requireRecordBody,
+  resolveAttemptCredential,
+  stripThinkingSuffix,
+} from "./native-shared";
 
 import type { GatewayHandlerDeps } from "./handler-deps";
 
-export type WebsearchHandlerDeps = GatewayHandlerDeps;
-
-
+type WebsearchHandlerDeps = GatewayHandlerDeps;
 
 /** Adapter that can serve a web-search request. */
 type WebsearchAdapter = ProviderAdapter & {
   websearch: NonNullable<ProviderAdapter["websearch"]>;
 };
 
-function jsonResponse(payload: unknown, status: number, requestId: string): Response {
-  return new Response(JSON.stringify(payload), {
-    status,
-    headers: {
-      "content-type": "application/json",
-      "cache-control": "no-store",
-      "x-request-id": requestId,
-    },
-  });
-}
-
 export function createWebsearchHandler(deps: WebsearchHandlerDeps) {
   return async ({ request }: { request: Request }): Promise<Response> => {
     const state = deps.stateStore.require(request);
     const authorization = state.authorization;
-    const body = state.ingressBody;
-    if (!authorization || body === null || typeof body !== "object" || Array.isArray(body))
-      throw new GatewayError("invalid_request", 400, "The search body must be a JSON object. Send one with at least a model and a query.");
-    const search = body as Record<string, unknown>;
+    const search = requireRecordBody(state, "The search body must be a JSON object (request {requestId}). Send one with at least a model and a query. Check the shape of what you sent — then resend 🪞");
+    // `requireRecordBody` already refused a missing authorization; this guard
+    // exists only to narrow the type for the code below.
+    if (!authorization) {
+      throw new GatewayError("invalid_request", 400, "authentication required (request {requestId})");
+    }
     if (typeof search.model !== "string" || search.model.trim().length === 0)
-      throw new GatewayError("invalid_request", 400, "A model is required: it names the search provider to use.");
+      throw new GatewayError("invalid_request", 400, "A model is required (request {requestId}): it names the search provider to use. Check the shape of what you sent — then resend 🪞");
     // The search "model" names the provider (or an alias/combo of one). A
     // thinking suffix is stripped for the same reason the canonical preparer
     // strips it: it is not part of any registered id.
-    const { model: bareModel } = parseThinkingSuffix(search.model);
-    const searchBody: Record<string, unknown> =
-      bareModel === search.model ? search : { ...search, model: bareModel };
-    if (!authorization.snapshot.scopes?.includes("search:invoke" as never)) {
-      throw new GatewayError("invalid_request", 403, "search not allowed for this key — enable search:invoke on the API key");
+    const { bareModel, body: searchBody } = stripThinkingSuffix(search.model, search);
+    if (!hasScope(authorization?.snapshot.scopes, "search:invoke")) {
+      throw new GatewayError("policy_rejected", 403, "search not allowed for this key (request {requestId}) — enable search:invoke on the API key. Not allowed by policy — no hard feelings 🫂");
     }
     // Trust boundary only: the query must be a non-empty string. The adapter
     // validates the remaining shape when it maps the body onto its provider.
     if (typeof search.query !== "string" || search.query.trim().length === 0)
-      throw new GatewayError("invalid_request", 400, "query is required");
+      throw new GatewayError("invalid_request", 400, "query is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
 
     const prepared = await deps.proxyPreparer.prepareNativeService({
       model: bareModel,
@@ -89,27 +82,15 @@ export function createWebsearchHandler(deps: WebsearchHandlerDeps) {
       candidates: prepared.candidates,
       tenantId: prepared.authorization.tenantId,
       strictPoolSelection: false,
-      exhaustedError: new GatewayError("admission_unavailable", 503, "no eligible search route"),
+      exhaustedError: new GatewayError("route_unavailable", 503, "no eligible search route (request {requestId}). The bouncer stepped out — come back shortly 🚪"),
       prepare: async (candidate) => {
-        const credential = candidate.provider_account_id
-          ? await resolveCredentialForAccount(
-              deps.db,
-              candidate.provider_id,
-              candidate.provider_account_id,
-              deps.oauthRefreshService && deps.resolveOAuthRefresher
-                ? { refreshService: deps.oauthRefreshService, resolveRefresher: deps.resolveOAuthRefresher }
-                : undefined,
-            )
-          : {
-              provider_id: candidate.provider_id as ProviderAdapter["provider_id"],
-              credential_kind: "none" as const,
-            };
+        const credential = await resolveAttemptCredential(deps, candidate);
         const adapter = (await deps.resolveProviderAdapter?.(candidate.provider_id)) as WebsearchAdapter | undefined;
         if (!adapter || typeof adapter.websearch !== "function")
           throw new GatewayError(
             "capability_unsupported",
             400,
-            "web search is unavailable for this provider",
+            "web search is unavailable for this provider (request {requestId}). Know your tools — this one just isn't in the box 🧰",
           );
         return { credential, adapter };
       },
@@ -132,14 +113,7 @@ export function createWebsearchHandler(deps: WebsearchHandlerDeps) {
           deadline: state.deadlineMs,
           abort_signal: state.abortController.signal,
           ...(candidate.user_agent === undefined ? {} : { user_agent: candidate.user_agent }),
-          ...(deps.networkBindingFactory
-            ? {
-                outbound_fetch: deps.networkBindingFactory.fetch(
-                  leases.proxySlot?.poolId,
-                  authorization.tenantId,
-                ),
-              }
-            : {}),
+          ...networkFetchContext(deps, leases.proxySlot?.poolId, authorization.tenantId),
         });
         const payload = {
           provider: candidate.provider_id,

package/src/transport/drain-endpoint.ts

@@ -20,7 +20,7 @@
 import { timingSafeEqual } from "node:crypto";
 import { GatewayError } from "../protocol/gateway-error";
 
-export interface DrainEndpointDeps {
+interface DrainEndpointDeps {
   /** Shared secret; the route is registered only when this is set. */
   readonly token: string;
   /** Begins the graceful drain (the process's own shutdown path). */
@@ -55,9 +55,9 @@ export function createDrainHandler(
 ): (context: { request: Request }) => Promise<Response> {
   return async ({ request }) => {
     if (!isLoopbackPeer(deps.resolvePeerAddress(request)))
-      throw new GatewayError("invalid_request", 403, "drain is only available from loopback");
+      throw new GatewayError("policy_rejected", 403, "drain is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂");
     if (!tokenMatches(request.headers.get("x-drain-token"), deps.token))
-      throw new GatewayError("invalid_request", 401, "invalid drain token");
+      throw new GatewayError("authentication_failed", 401, "invalid drain token (request {requestId}). Wrong key, right door — check the token 🔑");
     // Acknowledge first, then drain: the response must be on the wire before the
     // shutdown path starts closing sockets, or the caller sees a dropped
     // connection instead of a 202.

package/src/transport/failure-policy.ts

@@ -167,7 +167,7 @@ export function statusToGatewayErrorCode(status: number): GatewayErrorCode {
   if (status === 413) return "request_too_large";
   if (status === 415) return "unsupported_media_type";
   if (status === 422) return "upstream_unprocessable";
-  if (status === 529) return "capacity_exhausted";
+  if (status === 529) return "upstream_overloaded";
   if (status >= 500 && status <= 599) return "platform_unavailable";
   return "invalid_request";
 }
@@ -274,7 +274,9 @@ export function classifyUpstreamFailure(error: unknown): UpstreamFailurePolicy {
         error.code === "capability_unsupported" ||
     error.code === "model_not_found" ||
     error.code === "admission_unavailable" ||
+    error.code === "route_unavailable" ||
     error.code === "capacity_exhausted" ||
+    error.code === "upstream_overloaded" ||
     // A provider max-inflight rejection: the plan's next sibling account may
     // have a free slot, exactly as with an API-key concurrency rejection.
     error.code === "provider_capacity_exhausted" ||
@@ -286,6 +288,7 @@ export function classifyUpstreamFailure(error: unknown): UpstreamFailurePolicy {
     error.code === "accounts_unavailable" ||
     error.code === "accounts_rate_limited" ||
     error.code === "quota_exceeded" ||
+    error.code === "rate_limited" ||
     error.code === "authentication_failed" ||
     error.code === "proxy_auth_required" ||
     error.code === "deadline_exceeded" ||
@@ -427,10 +430,14 @@ const CATEGORY_HTTP_STATUS: Partial<Record<GatewayErrorCode | "unknown_error", n
   // in this process.
   transport_unavailable: 502,
   platform_unavailable: 502,
+  upstream_overloaded: 529,
   deadline_exceeded: 504,
   transport_closed: 499,
   shutting_down: 503,
   overloaded: 529,
+  route_unavailable: 503,
+  model_not_allowed: 403,
+  rate_limited: 429,
   unknown_error: 500,
 };
 
@@ -624,7 +631,7 @@ export function upstreamQueuedError(
     503,
     detail.length > 0
       ? detail
-      : "The upstream has queued this request. Retry after the stated interval.",
+      : "The upstream has queued this request (request {requestId}); retry after the stated interval. You're in line — no cuts 💛",
     {
       providerId,
       reason: "upstream-queued",
@@ -649,6 +656,12 @@ const QUOTA_ERROR_IDENTIFIERS: ReadonlySet<string> = new Set([
   // it is a spend/limit verdict, never an auth one, so it must classify as
   // quota (a cooldown) instead of `auth_invalidated`.
   "110",
+  // Qoder also reports quota exhaustion as `{"code":116,"error":"quota
+  // exceeded"}` (seen on the IDE model-server surface with a 499/stream
+  // close). The 499 special-case below already treats qoder 499 as quota;
+  // naming the code here makes any status that carries it classify as quota
+  // instead of `invalid_request`/`authentication_failed`.
+  "116",
   // InferHub publishes its own vocabulary in `error.code`. The two 403s below
   // are deliberate absences: `account_blocked` means the account was blocked
   // (an auth/entitlement verdict, not a spend limit) and
@@ -816,7 +829,7 @@ export function classifyUpstreamError(
   }
   if (normalized !== undefined && CAPACITY_ERROR_IDENTIFIERS.has(normalized))
     return {
-      code: "capacity_exhausted",
+      code: "upstream_overloaded",
       status: status === 503 || status === 529 ? status : 529,
       origin: "upstream",
     };
@@ -969,7 +982,7 @@ export async function throwIfHtmlResponse(response: Response): Promise<void> {
   throw new GatewayError(
     "transport_unavailable",
     502,
-    `Upstream returned an HTML error page: ${summary}`.slice(0, 300),
+    `Upstream returned an HTML error page: ${summary} (request {requestId}). The provider's edge is having a moment — hang tight ☕️`.slice(0, 320),
     { upstreamStatus: response.status, contentType, accountScope: true },
     "upstream",
   );
@@ -1011,11 +1024,11 @@ export function fallbackRetryDelayMs(attemptIndex: number): number {
 
 /** Sleeps until the delay expires or the request is aborted. */
 export function sleep(ms: number, signal: AbortSignal): Promise<void> {
-  if (signal.aborted) return Promise.reject(new GatewayError("transport_closed", 499, "request was cancelled"));
+  if (signal.aborted) return Promise.reject(new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃"));
   if (ms <= 0) return Promise.resolve();
   const { promise, resolve, reject } = Promise.withResolvers<void>();
   const timer = setTimeout(() => { signal.removeEventListener("abort", onAbort); resolve(); }, ms);
-  const onAbort = () => { clearTimeout(timer); reject(new GatewayError("transport_closed", 499, "request was cancelled")); };
+  const onAbort = () => { clearTimeout(timer); reject(new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃")); };
   signal.addEventListener("abort", onAbort, { once: true });
   return promise;
 }

package/src/transport/guards/auth-guard.ts

@@ -20,12 +20,6 @@ import { createAccessDecision } from "../../security/access-control";
 export function createApiKeyAuthenticationMiddleware(deps: {
   readonly db: CartethyiaDatabase;
   readonly stateStore: ProxyRequestStateStore;
-  /**
-   * Model-abuse ban gate. A banned IP or key is refused here, before the
-   * canonical parse and route preparation, and before `state.authorization` is
-   * assigned — so a banned caller's attempts produce no telemetry row and no
-   * console error, which is exactly the noise this layer exists to stop.
-   */
   /**
    * Tenant invoke kill switch. Checked after the key resolves, because the
    * tenant is a property of the key: the same gateway serves several tenants
@@ -62,9 +56,9 @@ export function createApiKeyAuthenticationMiddleware(deps: {
         safe.name = error instanceof Error ? error.name : "Error";
         log.error("[auth] key lookup failed; treating as unavailable", safe);
         throw new GatewayError(
-          "accounts_unavailable",
+          "admission_unavailable",
           503,
-          "The gateway could not verify this API key because its credential store is unavailable. Retry shortly.",
+          "The gateway could not verify this API key because its credential store is unavailable (request {requestId}). Retry shortly. The bouncer stepped out — come back shortly 🚪",
           {},
           "cartethyia",
         );
@@ -76,7 +70,7 @@ export function createApiKeyAuthenticationMiddleware(deps: {
         scopes: authorization.scopes,
       });
       if (!decision.scopes.includes("routing:invoke"))
-        throw new GatewayError("invalid_request", 403, "This API key is not allowed to invoke routing. Grant it the routing:invoke scope, or use a key that has it.");
+        throw new GatewayError("policy_rejected", 403, "This API key is not allowed to invoke routing (request {requestId}). Grant it the routing:invoke scope, or use a key that has it. Not allowed by policy — no hard feelings 🫂");
       // Kill switch: refuse before any upstream is touched. Distinct from the
       // scope check above, which is a property of the key — this is the tenant
       // having stopped all traffic, and it applies to every key the tenant owns.
@@ -86,7 +80,8 @@ export function createApiKeyAuthenticationMiddleware(deps: {
         throw new GatewayError(
           "platform_unavailable",
           503,
-          "This gateway has invoke switched off. Nothing upstream is being dialed while the switch is off; turn it back on from the dashboard overview to resume routing.",
+          "This gateway has invoke switched off (request {requestId}). Nothing upstream is being dialed while the switch is off; turn it back on from the dashboard overview to resume routing. Flip the switch back on when ready 🔌",
+          { reason: "invoke_switched_off" },
         );
       // A key may refuse a downstream router it has been resold to. This is a
       // policy check on the resolved key, so it belongs with the other
@@ -100,7 +95,7 @@ export function createApiKeyAuthenticationMiddleware(deps: {
         throw new GatewayError(
           "client_router_denied",
           403,
-          "No API invocation access for this client.",
+          "No API invocation access for this client (request {requestId}). This router isn't on the guest list — denied, but politely 🤗",
           { reason: "client_router_denied", clientRouter: denied },
         );
       deps.stateStore.require(request).authorization = authorization;