# Error codes: `@ultimat3/http` Part of [Error codes](Error-Codes): every code `@ultimat3/http` registers. `x errors explain --json` prints the same row. | Code | Means | Typical cause | Fix | |---|---|---|---| | `X_BEARER_MOUNT_INVALID` | a bearer mount declaration cannot be served as written | defineApi({ http: { mounts } }) named a primitive nothing registered, or a prefix that would shadow a framework namespace | `mounts: [{ prefix: '/v1', scopes: { 'cases:read': ['caseList'] }, resolveToken }]` in `defineApi({ http })` — a prefix that is not /api or /_x, and a scopes map naming only registered actions and queries (`x routes --json` lists them) | | `X_BODY_INVALID` | request body failed its schema | a plain `runtime.ts` route declaring `meta.input` was sent the wrong shape — an action or query answers `X_INPUT_INVALID` instead | `x routes --surface api --json` to find the route, then send a body its `meta.input` schema accepts | | `X_BODY_TOO_LARGE` | request body over the transport ceiling | the request declares or streams more bytes than http.maxRequestBodyBytes, the most this process reads for any route; a signed upload bigger than that cannot be accepted in one request | `send it in parts (storage signPart/completeUpload for an upload), or raise the ceiling: configureHttp({ maxRequestBodyBytes: }) in the app's http.ts` | | `X_BUILD_SKEW` | client build id does not match the server build id | a tab open across an incompatible deploy | `await navigator.serviceWorker.getRegistration().then((r) => r?.unregister())` in a stale tab the service worker cannot recover; one that can recovers on this response. See [PWA and offline](PWA-And-Offline) | | `X_CORS_CONFIG_INVALID` | the cors config can never produce a working response | `cors.origins` contains `'*'` while `cors.credentials` is true — a pair no browser accepts, which used to resolve to no CORS headers at all rather than an error — or contains `'null'`, the origin every sandboxed iframe sends, which `URL.parse('localhost:3000').origin` produces | call `configureHttp({ cors: { credentials: false } })` at module scope in a file under `apps/*/`, or replace `origins: ['*']` with the exact origins allowed to call this app; for `'null'`, list the scheme: `configureHttp({ cors: { origins: ['http://localhost:3000'] } })` | | `X_CSP_DIRECTIVE_INVALID` | a csp extension would emit something other than the directive it names | a `security.csp.extend` key that is not a CSP directive token, or a source carrying one of the header's own separators — `{ 'x; script-src *': [] }` is not one badly named directive, it is a second directive nobody declared, widening the one the framework locks down hardest. Refused at `defineHttpConfig`, because there is no encoding for a CSP directive and escaping it at emission time is not a repair | `configureHttp({ security: { csp: { extend: { 'img-src': ['https://cdn.example.com'] } } } })` — one entry per directive, each source its own array element; a directive name is `[a-z][a-z0-9-]*`, and no source may contain a space, a comma or a semicolon | | `X_CSRF_BLOCKED` | an unsafe request that did not prove same-origin | a state-changing request a browser sent — carrying its ambient session cookie, or anonymously (a forged sign-in) — whose `Origin` is not one this app allows. Never a 401: who is calling was never the question. An anonymous request carrying neither `Origin` nor `sec-fetch-site` is not judged | from a loopback client, the `curl -H 'sec-fetch-site: same-origin'` line it prints, with the request's own origin and path. Otherwise `configureHttp({ cors: { origins: [''] } })`, or call it with an `Authorization: Bearer` token instead of the session cookie, or `configureHttp({ csrf: { mode: 'off' } })` if this app has no cookie session at all | | `X_ERROR_STATUS_INVALID` | an error code cannot be mapped to that status | `registerErrorStatus()` given a framework-owned code, a status outside 100–599, or a second, different status for one code | `x errors list --json`, then map a code this app owns to a status the framework does not already hold | | `X_EXERCISE_REQUEST_INVALID` | an exercise entry's request is not one a browser could send | a request: in apps/web/exercise.ts names a cookie outside the token set, puts a Cookie header beside cookies, or a header Headers refuses | `defineExercise({ : { request: { cookies: { : '' }, headers: { '': '' } } } })` — in apps/web/exercise.ts | | `X_METHOD_NOT_ALLOWED` | route exists but not for this method | GET against an action endpoint | `x routes --json` — the path has no route for that method: add one, or call it with the method in `cause` | | `X_NO_REQUEST` | the inbound request is not in scope here | `useRequestCookie()` / `setRedirect()` called from a job, a task or a module body | `useRequestCookie(name)` inside a route handler, an action or a page; a job reads it at enqueue time and gets the value from its payload | | `X_OVERLOADED` | in-flight requests are at the configured ceiling | more concurrent requests than `maxInflight` (1,000). Shed **before** any work — no route match, no auth, no body, no query — because the alternative is not "serve everyone" but "serve nobody": every request queues behind the same pool, p99 walks off the chart and client retries multiply the load. `@ultimat3/realtime`'s `AcceptBudget` is the same decision for sockets. Classified `retry-after`, and the response carries the header; also thrown by `@ultimat3/auth`'s KDF gate, which refuses a password hash when 8 are running and 64 are queued — each argon2id arena is ~19 MiB, so the caps bound memory the per-IP limiters cannot | `configureHttp({ maxInflight: 2000 })` to serve more at once, at module scope in a file under `apps/*/`, with replicas to match — a caller retries after the `Retry-After` header. For the KDF half, `installKdfGate({ maxConcurrent, maxQueued })` from `@ultimat3/auth/adapter`, in `apps/web/runtime.ts` | | `X_PATH_INVALID` | a path segment is not valid percent-encoding | a hand-built URL, or a value concatenated into a path instead of run through `encodeURIComponent` — `%ZZ`, a lone `%`, a truncated `%A`. Answers 400: the client wrote the path, so the client is who can fix it, and the request never reaches a handler | `encodeURIComponent(value)` — send the segment percent-encoded; a literal `%` is `%25` | | `X_PIPELINE_FINALIZE_FAILED` | a finalize stage threw instead of finishing the response | the response cannot take the headers the pipeline puts on it — a `Response.redirect()`, or a frozen or proxied `Response` a handler returned. `handle()` answers this 500 rather than rejecting, and the `cause` names the stage | `jsonResponse(data)` — return a Response built here, or `textResponse()`, `html()`, `redirect()` from `@ultimat3/http` | | `X_PIPELINE_NO_RESPONSE` | a pipeline stage produced no response | a middleware returned `undefined` | `jsonResponse(data)` — return a `Response` from the route handler, or from the stage that short-circuits | | `X_PROBLEM_META_INVALID` | a problem document cannot carry that meta declaration | `registerProblemMeta()` given a framework-owned code (its `meta` is operator-only — the body excerpt `bodyInvalid` keeps there, the limiter's key), a key that is not one (`issues` already rides at the document's top level; `__proto__`), an empty list, or a second, different list for one code | `registerProblemMeta({ X_YOUR_CODE: ['sessionId'] })` with the keys your own error puts in `meta`, beside its `registerErrorStatus()` call — both are needed, because a code with no status is an unclassified 5xx whose `meta` is blanked with its `cause` | | `X_RATE_LIMITED` | rate limit exhausted for this key | bucket empty. One request spends a LIST of keys — the caller's, then the tenant's when `rateLimit.tenantBucket` is declared — and stops at the first refusal, so `meta.key` names which one | `configureHttp({ rateLimit: { buckets } })` to raise the bucket, at module scope in a file under `apps/*/` — or retry after `Retry-After` | | `X_RATE_LIMIT_BUCKET_CONFLICT` | one bucket has two declarations that disagree | an action's `rateLimit` and a `rateLimit.buckets.` entry passed to `configureHttp()` name different numbers, or two routes claim one bucket name. Refused at `httpServer`/`httpPipeline`, **before the socket opens** — picking a winner leaves the loser a number someone reads and nothing applies. An identical restatement passes | **one edit, not a choice**: delete `rateLimit.buckets.` from the app's `configureHttp()` call. The route is authoritative because it sits beside the handler and is what the OpenAPI operation publishes, so a config entry duplicating it is the copy that goes stale — the cause says so, and says which numbers came from where | | `X_RATE_LIMIT_BUCKET_UNBOUND` | the installed limiter does not hold a bucket a route declares | a limiter passed through `PipelineDeps.limiter` was built by the app from a config that never saw the routes, so every route-declared limit silently reverted to `default` — measured before the fix: 21 of 21 requests allowed against a route declaring 5, with `ratelimit-limit: 120` on the wire. Refused rather than rebound, because a `RateLimiter` is opaque and "binding" it would mean discarding the caller's limiter **and its store**. An absent bucket table is refused exactly as a wrong one is: what cannot be shown to hold is not assumed to hold | pass the **store** and let the pipeline build the limiter — `httpServer({ routes, rateLimitStore })` — so the bucket table is the one the routes registered | | `X_RATE_LIMIT_INVALID` | a declared rate limit computes to numbers the limiter cannot run on | a `{ limit, windowMs }` pair `toBucket` cannot convert: `limit` below 1 refuses the first caller, which is a policy's job and never a rate limit's, and `windowMs: 0` or `{ limit: MAX_VALUE, windowMs: 1 }` compute an infinite refill — a bucket that never empties. Raised in `@ultimat3/http`, which owns `Bucket` and the maths, so an action's and a query's `rateLimit:` are refused by one check and not two | `rateLimit: { limit: 5, windowMs: 600_000 }` on the declaration `cause` names — a whole allowance over a real window, here five per ten minutes — or delete it to keep the `default` bucket | | `X_RATE_LIMIT_NOT_SHARED` | the app declared a fleet-wide rate limit and the store keeps its counters per process | `rateLimit.scope: 'shared'` against `memoryRateLimitStore()`, whose `scope` is `'process'`. `assertRateLimitScope` compares the two inside `httpPipeline`, **before the socket opens** — the outcome it PREVENTS is N replicas each enforcing the full bucket, so a declared `limit: 5` costs 5 × N, silently. Also raised when `enabled: false` sits under `scope: 'shared'`: a fleet-wide limit switched off is a claim with nothing behind it | install a shared store — `httpServer({ routes, rateLimitStore: postgresRateLimitStore({ executor }) })` — or drop to `scope: 'process'` and terminate the limit at a shared proxy instead | | `X_RATE_LIMIT_SCOPE_UNSET` | the deployment has not said where the rate limiter keeps its counters | an enabled `rateLimit` with no `scope`, at `defineHttpConfig`. Reachable only from an embedder that builds its own config: `scope` is boot-owned, so `configureHttp()` type-refuses it and a process booted by `x dev` or `apps/web/server.ts` DERIVES it from the store it installed. `scope` used to **default** to `'process'`, so `login: { limit: 5 }` against the 3 `web` replicas this repo's own chart ships enforced 15 per window, with a green `x verify` and nothing anywhere to read. `assertRateLimitScope` only ever fired for an app that said `'shared'`, so the silent case was exactly the one nobody declared. One process is still a legal answer; it is no longer an assumed one | `defineHttpConfig({ rateLimit: { scope: 'process' } })` if this app runs as ONE replica, or `scope: 'shared'` plus `httpServer({ routes, rateLimitStore: postgresRateLimitStore({ executor }) })` for a fleet-wide limit | | `X_RATE_LIMIT_STORE_TIMEOUT` | the shared rate-limit store did not answer inside its own deadline | the database the shared rate-limit store counts in did not answer a take or peek within postgresRateLimitStore deadlineMs (250 ms by default), so this pod decided that request from its own memory | `x doctor --json` — names the database binding this pod cannot reach; a database that is slow rather than gone takes postgresRateLimitStore({ executor, deadlineMs }) raised in the boot that builds it | | `X_RATE_LIMIT_STORE_UNAVAILABLE` | the shared rate-limit store did not answer, so nothing decided | the `PgExecutor` handed to `postgresRateLimitStore` returned no row for a statement whose `returning` clause always produces one — a swallowed driver error, a pooler that dropped the statement, or an executor that maps `returning` away. Raised rather than defaulted: a limiter that cannot read its bucket has no safe assumption, and guessing `allowed` hands out the fleet-wide budget to every replica at once | `psql "$DATABASE_URL" -c "select * from x_rate_limit limit 1"` — then confirm the `PgExecutor` passed to `postgresRateLimitStore` returns the rows of `returning` | | `X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN` | the tenant allowance names a bucket nothing declares | `rateLimit.tenantBucket: 'tenant'` with no `rateLimit.buckets.tenant` beside it. Refused at `defineHttpConfig`, **before the socket opens**, and not on the first request: `bucketFor` resolves an unknown name to `default`, so a whole tenant's cap written as 5,000 would silently be the 120-burst `default` — looser than the declaration and visible nowhere. The cause lists every bucket name that IS declared | `configureHttp({ rateLimit: { tenantBucket: '', buckets: { '': { capacity: 5000, refillPerSecond: 100 } } } })` — the bucket declared beside the name — or drop `tenantBucket` to leave this app with no per-tenant allowance | | `X_ROUTE_CONFLICT` | two routes claim the same path | a copied route file | `x routes --json`, then remove or rename one | | `X_ROUTE_NOT_FOUND` | no route matches this request | path typo, or the route was never generated. Under `/api/` no route file applies: every path there is an action or a query `defineApi()` mounts | `x routes --json`, then `x g route ` — under `/api/`, `x routes --json` alone: call an endpoint it lists | | `X_SERVER_NOT_STARTED` | server handle used before `start()` | reading `url()` too early in a test | `httpServer({ … }).start()` before reading `url()` | | `X_TRUST_PROXY_UNSET` | proxy headers are trusted without saying how many proxies are in front | `trustProxy: true` with no `trustedProxyHops`. The leftmost `x-forwarded-for` entry is whatever the client typed, so without a hop count there is no way to tell the proxy's entry from the caller's — and every per-ip limit and lockout is then keyed on an address the caller chooses. Asked at `defineHttpConfig` in the same shape as `X_RATE_LIMIT_NOT_SHARED`, because only the app knows its own topology. Both keys are **boot-owned** and `configureHttp()` type-refuses them: a framework-booted process reads the hop count from the ENVIRONMENT, because one image runs behind an ingress in one cluster and behind nothing on a laptop | set `TRUSTED_PROXY_HOPS` in the deployment environment to the number of proxies that append to `x-forwarded-for` — 1 for a single ingress or ALB, 2 for a CDN in front of one — and leave it unset for a process reached directly (`trustedHopsFromEnv`, [`packages/cli/src/role-start.ts`](https://github.com/developerz-ai/ultimate/blob/main/packages/cli/src/role-start.ts)). An embedder calling `defineHttpConfig` itself passes `{ trustProxy: true, trustedProxyHops: 1 }` | | `X_WEBHOOK_SIGNATURE_INVALID` | the inbound webhook is not signed by the holder of this secret | four conditions, one code: no readable `x-ultimate-webhook-signature`, an id or topic header outside 1–200 characters or carrying a `:` or a control character, a mac that does not match the bytes that arrived, or a secret the two sides disagree about. The header check is refused **before** the mac is taken — the signed string is `v1::::`, so id `evt:01HZ` with topic `orders.paid` and id `evt` with topic `01HZ:orders.paid` build the SAME bytes, one mac authenticating two differently-labelled deliveries. **401 and never 400**: the request is well formed and carried a CREDENTIAL, so what failed is authentication. Never 403 either, which means an authenticated caller was refused, and there is none here. Does not trigger `signInRedirect`, which keys on `X_UNAUTHENTICATED` alone — a sender is not a browser and has no session to go get. `cause` names only what the framework chose: never the signature, never the secret, never the body | `verifyWebhookSignature(request, { secret })` with the secret this endpoint was registered under — re-read it from your sender dashboard, and sign each delivery with it | | `X_WEBHOOK_SIGNATURE_STALE` | the inbound webhook is signed correctly and is too old to accept | the mac verified and the timestamp sits further than `toleranceMs` (default 300,000 ms) from this clock — a sender's clock, or a delivery replayed off a capture. The mac is checked **before** the window, deliberately, so this code always means "authentic and old" and never "unreadable and old". Both directions of skew count: a sender running ahead is the same replay window pointed the other way, and accepting the future half doubles it. Same 401 as above — the credential is a timestamped one and this is its expiry half | `verifyWebhookSignature(request, { secret, toleranceMs: 600_000 })` if the sender queues deliveries for longer than that — otherwise sync the sending host clock with NTP |