Decide the public status of `ContextPipelineInterruptedError` before 4.0

Author: janbucharCreated Sep 18, 2026Updated Sep 22, 2026

Labelst-tooling

related to #3264
Throwing it from preNavigationHooks / extendContext is currently the only way to skip a request without it counting as a failure — no retry, no requestsFailed, no error log, request marked handled. It replaces the v3 hack of noRetry + throw + decrementing requestsFailed + patching log.error.
It is exported @public from @crawlee/basic but has no JSDoc or guide entry, its message talks about "context initialization", it is only honoured from pipeline middleware (from requestHandler it is wrapped in RequestHandlerError and treated as a normal failure), it bypasses onSkippedRequest and never sets request.state = SKIPPED, and the request transaction rolls back anything written before the throw.
Two ways out: bless it (document it, honour it from requestHandler too, route it through the same skip bookkeeping as the robots.txt / redirect skips), or mark it @internal now and add context.skipRequest(reason?) as the public API.
Un-exporting it and changing how requestHandler treats it are both cheap before stable; skipRequest() itself is additive and can follow.

Source: apify/crawlee