Skip to main content

Troubleshooting

No HTTP server starts​

@quik/http only defines the abstract engine contract and routing decorators — it does not implement a server. The IQHTTPEngine feature is initialized solely when the bootstrap startHttpServer flag is set, and it stays unregistered until an implementation package (such as @quik/http-express) is also loaded.

Route not reachable​

Routes must extend QRoute (or QServerEventRoute for SSE routes) and be decorated with Decorators.Route.Route(path); otherwise the router rejects them with quik.errors.http.route.invalid-parent. Confirm the route file is actually imported somewhere in the bootstrap chain — decorators only register a class once its module is loaded.

Response validation error​

An endpoint handler must return a plain object (or Promise of one) for it to be serialized as a QResponse; if the engine adapter cannot map the returned value it raises quik.errors.http.invalid-response / quik.errors.framework.invalid-response-parameters.

Body validation failures​

Requests with an invalid body/query/path entity produce quik.errors.http.body-validation-error, with the underlying validation messages interpolated into {{message}}.

Rate limit not enforced​

@RateLimit({ max, windowMs }) is keyed on client IP using the default QInMemoryRateLimiter, which is per-process and resets on restart. For multi-instance deployments, call setRateLimiter(impl) with a shared backend (e.g. Redis-backed) before traffic hits the rate-limited endpoints.

Common Errors​

  • quik.errors.http.bad-request / forbidden / unauthorized / gone / page-not-found / server-error / unprocessable-entity / teapot / keep-calm: thrown by the matching typed error class (BadRequestError, ForbiddenError, UnauthorizedError, GoneError, PageNotFoundError, ServerError, UnprocessableEntityError, TeapotError, KeepCalmError).
  • quik.errors.http.invalid-credentials: thrown by InvalidCredentialsError when supplied credentials fail validation.
  • quik.errors.http.tooManyRequests: thrown by TooManyRequestsError (maps to HTTP 429) when a rate limit is exceeded.
  • quik.errors.http.body-validation-error / body-should-be-array: request body failed entity validation.
  • quik.errors.http.invalid-response: an endpoint handler did not return a valid QResponse-compatible value.
  • quik.errors.http.route.client-not-found: a Server-Sent Events client ID does not exist.
  • quik.errors.http.route.invalid-parent: a route class does not extend QRoute/QServerEventRoute.
  • quik.errors.framework.invalid-response-parameters: invalid parameters were passed when constructing a response.