cartethyia 2.7.3 → 2.7.4

package/src/transport/dispatch/proxy-request.ts

@@ -116,7 +116,7 @@ export async function handleProviderProxyRequest(
   const state = deps.stateStore.require(request);
   const prepared = state.preparedRequest;
   if (!prepared)
-    throw new GatewayError("admission_unavailable", 503, "The request was not prepared, so no route can be dialed. Resend the request.");
+    throw new GatewayError("route_unavailable", 503, "The request was not prepared, so no route can be dialed (request {requestId}). Resend the request. The bouncer stepped out — resend shortly 🚪");
   const canonicalRequest = await applyTenantPreferences(prepared, deps.db);
   // Tenant system-prompt injection, resolved once per request. For providers
   // whose upstream validates the fixed system prompt as a channel identity
@@ -188,13 +188,13 @@ export async function handleProviderProxyRequest(
     tenantId: prepared.authorization.tenantId,
     strictPoolSelection: true,
     resolveHost: (candidate) => deps.byokUpstreamHosts?.get(candidate.provider_id),
-    exhaustedError: new GatewayError("admission_unavailable", 503, "No account could be leased for this request. Retry shortly; if it persists, add an account or check that one is healthy."),
+    exhaustedError: new GatewayError("route_unavailable", 503, "No account could be leased for this request (request {requestId}). Retry shortly; if it persists, add an account or check that one is healthy. The bouncer stepped out — come back shortly 🚪"),
     prepare: async (candidate) => {
       if (!candidate.provider_account_id && candidate.requires_account !== false)
         throw new GatewayError(
-          "admission_unavailable",
+          "route_unavailable",
           503,
-          "This route has no usable credential. Save one on the account, or route to a provider whose account is configured.",
+          "This route has no usable credential (request {requestId}). Save one on the account, or route to a provider whose account is configured. Wrong key, right door — check the credential 🔑",
         );
       const credential = candidate.provider_account_id
         ? await resolveCredentialForAccount(
@@ -211,13 +211,13 @@ export async function handleProviderProxyRequest(
           };
       const adapter = await deps.resolveProviderAdapter?.(candidate.provider_id);
       if (!adapter)
-        throw new GatewayError("admission_unavailable", 503, "provider adapter not registered");
+        throw new GatewayError("route_unavailable", 503, "provider adapter not registered (request {requestId}). Even we have bad days — check the registry wiring 🐻");
       if (!isBundledProviderId(candidate.provider_id)) {
         if (!deps.byokUpstreamHosts?.get(candidate.provider_id) || !deps.networkBindingFactory)
           throw new GatewayError(
-            "admission_unavailable",
+            "route_unavailable",
             503,
-            "validated network binding is required for configurable upstreams",
+            "validated network binding is required for configurable upstreams (request {requestId}). No bridge to cross — configure a pool first 🏗️",
           );
       }
       return { credential, adapter };

package/src/transport/dispatch/responses-compact.ts

@@ -27,10 +27,10 @@ export function createResponsesCompactHandler(deps: ResponsesCompactHandlerDeps)
     const authorization = state.authorization;
     const body = state.ingressBody;
     if (!authorization || body === null || typeof body !== "object" || Array.isArray(body))
-      throw new GatewayError("invalid_request", 400, "compact request body must be a JSON object");
+      throw new GatewayError("invalid_request", 400, "compact request body must be a JSON object (request {requestId}). Check the shape of what you sent — then resend 🪞");
     const compact = body as Record<string, unknown>;
     if (typeof compact.model !== "string" || compact.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 here for the same reason the
     // canonical preparer strips it: this route matches the model name against
     // the allowlist and the route plan, and `(high)` is not part of any
@@ -43,18 +43,18 @@ export function createResponsesCompactHandler(deps: ResponsesCompactHandlerDeps)
     const compactBody: Record<string, unknown> =
       compactModel === compact.model ? compact : { ...compact, model: compactModel };
     if (!(typeof compact.input === "string" || Array.isArray(compact.input)))
-      throw new GatewayError("invalid_request", 400, "input must be a string or array");
+      throw new GatewayError("invalid_request", 400, "input must be a string or array (request {requestId}). Check the shape of what you sent — then resend 🪞");
     if ("instructions" in compact && typeof compact.instructions !== "string")
-      throw new GatewayError("invalid_request", 400, "instructions must be a string");
+      throw new GatewayError("invalid_request", 400, "instructions must be a string (request {requestId}). Check the shape of what you sent — then resend 🪞");
     if (compact.stream === true)
       throw new GatewayError(
         "capability_unsupported",
         400,
-        "Responses compact does not support streaming",
+        "Responses compact does not support streaming (request {requestId}). Know your tools — this one just isn't in the box 🧰",
       );
     const adapter = (await deps.resolveProviderAdapter?.("codex")) as CodexCompactAdapter | undefined;
     if (!adapter || typeof adapter.compact !== "function")
-      throw new GatewayError("admission_unavailable", 503, "Codex compact transport unavailable");
+      throw new GatewayError("admission_unavailable", 503, "Codex compact transport unavailable (request {requestId}). The bouncer stepped out — come back shortly 🚪");
     const prepared = await deps.proxyPreparer.prepareNativeCompact({
       model: compactModel,
       authorization,
@@ -77,16 +77,16 @@ export function createResponsesCompactHandler(deps: ResponsesCompactHandlerDeps)
       // Lenient pool semantics: a missing slot tolerates direct egress.
       strictPoolSelection: false,
       exhaustedError: new GatewayError(
-        "admission_unavailable",
+        "route_unavailable",
         503,
-        "no eligible Codex route",
+        "no eligible Codex route (request {requestId}). The bouncer stepped out — come back shortly 🚪",
       ),
       prepare: async (candidate) => {
         if (!candidate.provider_account_id)
           throw new GatewayError(
-            "admission_unavailable",
+            "route_unavailable",
             503,
-            "Codex compact requires an OAuth account",
+            "Codex compact requires an OAuth account (request {requestId}). Wrong key, right door — check the credential 🔑",
           );
         const credential = await resolveCredentialForAccount(
           deps.db,
@@ -100,7 +100,7 @@ export function createResponsesCompactHandler(deps: ResponsesCompactHandlerDeps)
           throw new GatewayError(
             "capability_unsupported",
             400,
-            "Responses compact requires a Codex ChatGPT OAuth account",
+            "Responses compact requires a Codex ChatGPT OAuth account (request {requestId}). Wrong key, right door — check the credential 🔑",
           );
         return { credential, adapter };
       },

package/src/transport/dispatch/retry-policy.ts

@@ -8,9 +8,12 @@
  * than inside it so the loop stays a policy *consumer* — one place decides
  * retryability (`../failure-policy.ts`), one place decides refresh and
  * cooldown eligibility (here).
+ *
+ * The egress-scoped half of the rate-limit decision lives in
+ * `../../network/rate-limit-verdict`; this module keeps only the credential-
+ * scoped predicates.
  */
 import { GatewayError } from "../../protocol/gateway-error";
-import { providerRateLimitIsIpScoped } from "../../providers/provider-metadata";
 
 /**
  * Returns true only when an upstream failure is evidence that the OAuth
@@ -32,69 +35,3 @@ export function isOAuthCredentialInvalidated(error: unknown): error is GatewayEr
   if (/web[ _-]?search|web[ _-]?fetch|x[ _-]?search|tool invocation|search backend/i.test(message)) return false;
   return error.details.credentialEvidence === true;
 }
-
-/**
- * A free-tier IP refusal: the upstream has flagged this egress address, not
- * this request.
- *
- * OpenCode answers a blocked address with `403` and its own
- * `FreeTierError`/`ModelDeprecated`-style body. The request was never read, so
- * retrying it — with the same tools, the same headers, or the same credential —
- * cannot succeed from the same address. Only a different egress can.
- *
- * This is deliberately narrower than "any 403": a content-policy rejection or a
- * licence refusal is also a 403 and must not retire a healthy proxy. The
- * provider must also declare `ipScopedRateLimit`, which is the same fact the
- * 429 path already relies on.
- */
-export function isFreeTierIpBlock(error: unknown, providerId: string): error is GatewayError {
-  if (!(error instanceof GatewayError) || error.origin !== "upstream" || error.status !== 403) {
-    return false;
-  }
-  if (!providerRateLimitIsIpScoped(providerId)) return false;
-  const providerCode = typeof error.details.providerCode === "string" ? error.details.providerCode : "";
-  const raw = String(error.details.raw ?? "");
-  return (
-    /freetier|free.?tier/i.test(providerCode) ||
-    /FreeTierError|free tier can only be used/i.test(`${error.message} ${raw}`)
-  );
-}
-
-/**
- * A provider-scoped 429, on a provider whose limits follow the egress address.
- *
- * Only then is the pool the thing that ran out: the upstream counted requests
- * from this address, so the next attempt must leave by a different one and
- * cooling this pool is the fix. `providerRateLimitIsIpScoped` holds that fact
- * per provider (see the metadata field) rather than inferring it from the
- * response — a 429 states which bucket was exhausted only in the provider's own
- * wording, and every account-keyed provider words it the same way.
- *
- * For an account-keyed provider the 429 belongs to the credential that was
- * dialed. The account health machine already records it and routes the next
- * request to a sibling, so cooling the pool as well only removed healthy
- * accounts from service: every account sharing that egress lost its route for
- * the cooldown window because one of them hit its own limit. A bare 429 with no
- * provider scope stays a request-level limit and never cools the pool.
- *
- * `providerId` is the caller's own candidate, not a field read off the error:
- * the in-stream error frames the protocol modules build carry no `providerId`
- * detail, so reading it from `details` would silently disable the IP-scoped
- * rule on exactly the streaming path it exists for.
- *
- * A type guard on `GatewayError`, so a caller that passes this check can hand
- * the same value to `flagPoolCooldown` without a second narrowing step.
- */
-export function shouldCooldownPool(error: unknown, providerId: string): error is GatewayError {
-  if (
-    !(
-      error instanceof GatewayError &&
-      error.origin === "upstream" &&
-      error.status === 429 &&
-      error.details.rateLimitScope === "provider"
-    )
-  ) {
-    return false;
-  }
-  return providerRateLimitIsIpScoped(providerId);
-}

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

@@ -60,7 +60,7 @@ export function createDispatchStreamEncoder(
   throw new GatewayError(
     "capability_unsupported",
     400,
-    `Unknown surface: ${surface}`,
+    `Unknown surface: ${surface} (request {requestId}). Know your tools — this one just isn't in the box 🧰`,
     { surface },
   );
 }

package/src/transport/dispatch/streaming/finalize.ts

@@ -24,7 +24,7 @@ import type { Reservation } from "../../routing/route-model";
 import { repriceUsage } from "../../../providers/provider-usage";
 import { metrics } from "../../../observability/metrics";
 import { flagPoolBlocked, flagPoolCooldown } from "../../../network/pool-health";
-import { isFreeTierIpBlock, shouldCooldownPool } from "../retry-policy";
+import { classifyEgressFailure } from "../../../network/rate-limit-verdict";
 import { releaseAttemptLeases } from "../leases";
 import type { AttemptLeaseOwnership } from "../leases";
 import { finalizeRequestTelemetry } from "../../guards/error-lifecycle";
@@ -186,7 +186,7 @@ export class StreamFinalizer {
       // origin is the upstream's: labelling it `cartethyia` reported a
       // provider that stopped sending as a gateway defect.
       this.input.state.abortController.abort(
-        new GatewayError("deadline_exceeded", 504, "The upstream stopped sending data mid-stream. Retry; if it keeps happening, the account or pool is unstable.", {}, "upstream"),
+        new GatewayError("deadline_exceeded", 504, "The upstream stopped sending data mid-stream (request {requestId}). Retry; if it keeps happening, the account or pool is unstable. The connection ghosted us — come back in a moment 👻", {}, "upstream"),
       );
     }, timeoutMs);
   }
@@ -363,7 +363,7 @@ export class StreamFinalizer {
     if (drain) return drain;
     if (reason instanceof GatewayError && reason.code === "deadline_exceeded") return reason;
     if (reason instanceof DOMException && reason.name === "TimeoutError")
-      return new GatewayError("deadline_exceeded", 504, "request deadline exceeded", {}, "cartethyia");
+      return new GatewayError("deadline_exceeded", 504, "request deadline exceeded (request {requestId}). Some things just take longer 🐢", {}, "cartethyia");
     return undefined;
   }
 
@@ -453,7 +453,7 @@ export class StreamFinalizer {
         ? new GatewayError(
             "transport_unavailable",
             502,
-            "The upstream closed the stream before it reported a final result. Retry; if it keeps happening, the account or pool is unstable.",
+            "The upstream closed the stream before it reported a final result (request {requestId}). Retry; if it keeps happening, the account or pool is unstable. The connection ghosted us — come back in a moment 👻",
             {},
             "upstream",
           )
@@ -531,7 +531,7 @@ export class StreamFinalizer {
           ? new GatewayError(
               "deadline_exceeded",
               504,
-              "request deadline exceeded",
+              "request deadline exceeded (request {requestId}). Some things just take longer 🐢",
               {},
               "cartethyia",
             )
@@ -579,10 +579,11 @@ export class StreamFinalizer {
       ...(pipeline.clientResponseText.length > 0 ? { clientResponseText: pipeline.clientResponseText } : {}),
     });
     this.streamSettled = true;
-    if (candidate.networkPoolId && !cancelled && deps.poolSelector) {
-      if (shouldCooldownPool(err, candidate.providerId)) {
+    if (candidate.networkPoolId && !cancelled && deps.poolSelector && err instanceof GatewayError) {
+      const egressVerdict = classifyEgressFailure(err, candidate.providerId);
+      if (egressVerdict.kind === "cooldown") {
         flagPoolCooldown(deps.poolSelector, deps.db, candidate.networkPoolId, candidate.providerId, err);
-      } else if (isFreeTierIpBlock(err, candidate.providerId)) {
+      } else if (egressVerdict.kind === "blocked") {
         flagPoolBlocked(deps.poolSelector, deps.db, candidate.networkPoolId, candidate.providerId, err);
       }
     }

package/src/transport/dispatch/systemone.ts

@@ -33,10 +33,10 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
     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");
+      throw new GatewayError("invalid_request", 400, "systemone request body must be a JSON object (request {requestId}). Check the shape of what you sent — then resend 🪞");
     const decision = body as Record<string, unknown>;
     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
@@ -49,14 +49,14 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
     // 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",
@@ -80,9 +80,9 @@ 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
@@ -103,7 +103,7 @@ export function createSystemoneHandler(deps: SystemoneHandlerDeps) {
           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 };
       },
@@ -148,7 +148,7 @@ 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

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

@@ -57,7 +57,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
       throw new GatewayError(
         "invalid_request",
         400,
-        "The count_tokens body must be a JSON object, the same shape POST /v1/messages accepts.",
+        "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 🪞",
       );
     }
     const countBody = body as Record<string, unknown>;
@@ -66,16 +66,16 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
     // 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)) {
       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 🫂",
       );
     }
 
@@ -111,9 +111,9 @@ 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
@@ -131,7 +131,7 @@ export function createTokenCountHandler(deps: TokenCountHandlerDeps) {
             };
         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 +146,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 = {

package/src/transport/dispatch/websearch.ts

@@ -50,10 +50,10 @@ export function createWebsearchHandler(deps: WebsearchHandlerDeps) {
     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.");
+      throw new GatewayError("invalid_request", 400, "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 🪞");
     const search = body as Record<string, unknown>;
     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.
@@ -61,12 +61,12 @@ export function createWebsearchHandler(deps: WebsearchHandlerDeps) {
     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");
+      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,7 +89,7 @@ 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(
@@ -109,7 +109,7 @@ export function createWebsearchHandler(deps: WebsearchHandlerDeps) {
           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 };
       },

package/src/transport/drain-endpoint.ts

@@ -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",
@@ -816,7 +823,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 +976,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 +1018,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

@@ -62,9 +62,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 +76,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 +86,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 +101,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;

package/src/transport/guards/body-policy.ts

@@ -77,11 +77,11 @@ export async function readIngressBody(
   const isJsonRoute = isJsonProxyRoute(p);
   const contentType = request.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
   if (!contentType) {
-    if (isJsonRoute) throw new GatewayError("unsupported_media_type", 415, "This endpoint reads JSON, so the request needs a content-type: application/json header.");
+    if (isJsonRoute) throw new GatewayError("unsupported_media_type", 415, "This endpoint reads JSON, so the request needs a content-type: application/json header (request {requestId}). We speak JSON here — send JSON 💬");
     return undefined;
   }
   if (contentType !== "application/json") {
-    if (isJsonRoute) throw new GatewayError("unsupported_media_type", 415, `This endpoint reads JSON and cannot parse '${contentType}'. Send content-type: application/json.`);
+    if (isJsonRoute) throw new GatewayError("unsupported_media_type", 415, `This endpoint reads JSON and cannot parse '${contentType}' (request {requestId}). Send content-type: application/json. We speak JSON here — send JSON 💬`);
     return undefined;
   }
   const maxBytes = options.maxBodyBytes ?? 1_048_576;
@@ -91,7 +91,7 @@ export async function readIngressBody(
     throw bodyTooLargeError(maxBytes);
 
   const reader = request.body?.getReader();
-  if (!reader) throw new GatewayError("invalid_request", 400, "The request body could not be read. Resend it with a JSON body.");
+  if (!reader) throw new GatewayError("invalid_request", 400, "The request body could not be read (request {requestId}). Resend it with a JSON body. Check the shape of what you sent — then resend 🪞");
   // Collect raw chunks then decode once. String `+=` on each chunk reallocates
   // the accumulating UTF-16 string (O(n²) for large Claude Code prompts);
   // Buffer.concat + one TextDecoder pass is linear and allocation-stable.
@@ -126,7 +126,7 @@ export async function readIngressBody(
     return body;
   } catch (error) {
     if (error instanceof GatewayError) throw error;
-    throw new GatewayError("invalid_request", 400, "The request body is not valid JSON. Check for a trailing comma or an unclosed brace.");
+    throw new GatewayError("invalid_request", 400, "The request body is not valid JSON (request {requestId}). Check for a trailing comma or an unclosed brace. Check the shape of what you sent — then resend 🪞");
   }
 }