Conventions

Headers

Request bodies

JSON, 4 MB maximum (express.json({ limit: '4mb' })). URL-encoded bodies share the limit.

The global ValidationPipe is configured:

new ValidationPipe({
  whitelist: true,
  transform: true,
  forbidNonWhitelisted: true,
  transformOptions: { enableImplicitConversion: true },
})

Response envelopes

Single record

A BaseModel<T> — platform fields at the top level, your payload under data.

{ "pk": "…", "sk": "6512ab…", "name": "Blue Widget", "datatype": "sf_product",
  "version": 3, "state": "published", "createdate": "…", "modifydate": "…",
  "data": { "price": 19.99, "sku": "BW-1" } }

List

A BaseModelDTO<T>.

{ "datatype": "sf_product", "total": 128, "page": 0, "pageSize": 25,
  "hasNext": true, "fromCache": false,
  "data": [ { "sk": "…", "data": { … } } ] }

Paging and query options

DataOptions fields are accepted on list and search endpoints:

Errors

A global filter (AllExceptionsFilter, registered as APP_FILTER) normalizes what handlers throw into one envelope:

{
  "statusCode": 401,
  "error": "Token has expired. Refresh the access token or request a new one.",
  "path": "/repository/get/customer/6512ab",
  "method": "GET",
  "timeStamp": "2026-08-28T10:00:00.000Z"
}

Non-HTTP exceptions are categorized first — MongoDB errors, for instance, are mapped to appropriate status codes rather than surfacing as a bare 500.

Structured auth errors

Auth failures are thrown with a richer shape, carrying a stable code and sometimes a recommended action:

Other common statuses

Rate limiting

Fixed window, applied before routing:

• Window: 15 minutes
• Limit: RATE_LIMIT_MAX, default 10000 per IP
• Headers: standard RateLimit-* (legacy X-RateLimit-* off)
• Exempt: /monitoring/health

{ "statusCode": 429, "error": "Too Many Requests",
  "message": "Too many requests from this IP, please try again later" }

The client IP is derived with trust proxy set to exactly TRUST_PROXY_HOPS hops (default 2 — Cloudflare, then Traefik). A specific count rather than true is what stops a client from spoofing X-Forwarded-For to escape the limit. Change your proxy topology and you must change this value.

The 429 handler sets CORS headers itself, because Nest applies CORS during init() — after this middleware — so short-circuited responses would otherwise reach the browser without them and surface as an opaque network error.

CORS

• Development: any origin, credentials allowed.
• Production: origins from ALLOWED_ORIGINS (comma-separated); methods GET, POST, PUT, DELETE, PATCH, OPTIONS; credentials allowed; preflight cached 24 h.

Route aliasing

Two patterns produce multiple URLs for one handler, and both appear in the auth module:

• Array controller prefixes — @Controller(['profile', 'user']) mounts everything under both.
• Array method paths — @Post(['/user/signin', '/signin']).

Combined, signin answers on four URLs. They are the same handler; pick one form per client.

Some handler paths also begin with /, which produces a doubled separator in naive path concatenation. The router normalizes it — /profile/whoami is correct, /profile//whoami is what you see if you build the path by hand.

Timeouts

Keep-alive is 65 s with a 66 s headers timeout — deliberately above a typical 60 s load-balancer idle timeout, so the balancer closes idle connections rather than letting them accumulate on the server.

Health and version

All three skip the tenant requirement. /health returns { isHealthy, services, timestamp } with 200 or 503, and sends Cache-Control: no-cache, no-store, must-revalidate.