ruvnet/ruflo · error

[router] tools fallback failed due to payment required

Error message

[router] tools fallback failed due to payment required

What it means

Log warning in makeRouterEndpoint: the tools-route bypass attempt failed with a payment-required class error (402), so the request is not retried on the tools model and routing proceeds to the fallback chain.

Source

Thrown at ruflo/src/ruvocal/src/lib/server/router/endpoint.ts:250

			} else {
				try {
					logger.info(
						{ route: ROUTER_TOOLS_ROUTE, model: toolsCandidate },
						"[router] tools active; bypassing Arch selection"
					);
					const ep = await createCandidateEndpoint(toolsCandidate);
					const gen = await ep({ ...params });
					return metadataThenStream(gen, toolsCandidate, ROUTER_TOOLS_ROUTE);
				} catch (e) {
					const { message, statusCode } = extractUpstreamError(e);
					const logData = {
						route: ROUTER_TOOLS_ROUTE,
						model: toolsCandidate,
						err: message,
						...(statusCode && { status: statusCode }),
					};
					if (statusCode === 402) {
						logger.warn(logData, "[router] tools fallback failed due to payment required");
					} else {
						logger.error(logData, "[router] tools fallback failed");
					}
					throw statusCode ? new HTTPError(message, statusCode) : new Error(message);
				}
			}
		}

		const routeSelection = await archSelectRoute(sanitizedMessages, undefined, params.locals);

		// If arch router failed with an error, only hard-fail for policy errors (402/401/403)
		// For transient errors (5xx, timeouts, network), allow fallback to continue
		if (routeSelection.routeName === ROUTER_FAILURE && routeSelection.error) {
			const { message, statusCode } = routeSelection.error;

			if (isPolicyError(statusCode)) {
				// Policy errors should be surfaced to the user immediately (e.g., subscription required)
				logger.error(

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Top up or fix billing for the fallback provider; HTTP 402 means the account cannot pay for the request.

When it happens

Trigger: Thrown at ruflo/src/ruvocal/src/lib/server/router/endpoint.ts:250 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/910b24e64135d818. Report an issue: GitHub.