Troubleshooting Superhighway

Superhighway guides

Empty results (results array is [])

The most common cause is that SearXNG's upstream search engines temporarily blocked our datacenter IP. This happens with no warning and resolves itself within minutes as we rotate engines.

Quick check:

curl "https://superhighway.walls.sh/search?q=test&key=YOUR_KEY"
# Healthy: {"results":[...], "count":10}
# Blocked: {"results":[], "count":0}

What to do:

Retry with exponential back-off — one retry after 2 s resolves most transient blocks. Two retries cover nearly all cases.
Broaden the query — very specific or niche queries can exhaust the engine pool faster. Try a shorter version.
Check /metrics — the live dashboard at /metrics shows empty_results_24h. Sustained spikes (>20 % of calls) indicate a systemic block we're actively rotating around.
Use /news as a fallback — news engines use a separate pool and are rarely blocked at the same time as web engines.

Persistent empty results for common queries? Email pat@walls.sh — we track these and rotate engines manually when needed.

401 Unauthorized

The API couldn't verify your key.

HTTP 401
{"error":"unauthorized","message":"Invalid or missing API key"}

Common causes:

Wrong header name — must be Authorization: Bearer YOUR_KEY, not X-API-Key or Api-Key.
Whitespace in the key — copy-paste from a .env file sometimes adds a trailing newline. Trim it.
Key passed as query param — use ?key=YOUR_KEY (not ?api_key= or ?apiKey=).
Wrong key — the key shown on /pricing after sign-up is the one that works. Keys are prefixed shwy_.

# Correct header form
curl -H "Authorization: Bearer shwy_your_key_here" "https://superhighway.walls.sh/search?q=ai+news"

# Correct query-param form
curl "https://superhighway.walls.sh/search?q=ai+news&key=shwy_your_key_here"

402 Payment Required (x402 flow)

You're hitting the pay-per-call lane without a funded wallet, or your wallet is on the wrong network.

HTTP 402
{"x402Version":1,"error":"Payment required","accepts":[...]}

Common causes:

Wallet not funded — the accepts[].maxAmountRequired field in the 402 body shows the price in USDC atomic units (6 decimals). 1000 = $0.001. Fund your wallet with USDC on Base mainnet.
Wrong network — must be Base mainnet (chain ID 8453), not Base Sepolia testnet. Check AGENT_PRIVATE_KEY points to a mainnet wallet.
Missing env var — the x402 client SDK reads AGENT_PRIVATE_KEY. Verify it's set in the process environment, not just in a .env file that wasn't loaded.

See the full wallet setup in the x402 pay-per-call guide. To avoid wallet management entirely, get a free API key instead — free tier covers 1,000 calls/month.

429 Rate Limited

HTTP 429
{"error":"rate_limit_exceeded","message":"Free tier: 1000 calls/month. Upgrade at /pricing."}

Free API keys are capped at 1,000 calls per calendar month. Options:

Check usage — usage resets on the 1st of each month. The reset date is in the 429 body.
Switch to x402 — pay-per-call has no monthly cap. Each call costs $0.001–$0.005 USDC, settled on-chain. See the x402 guide.
Upgrade plan — higher-volume Stripe plans are available at /pricing.

/research is slow

/research is intentionally a multi-step operation: it searches, fetches the top result pages, and synthesises them into a single answer. Expect 5–15 seconds — this is normal. If you need a lower-latency response, use /search and process results yourself.

# Fast — raw results, you do the reading
GET /search?q=your+question

# Thorough — Superhighway reads the pages for you (5–15 s)
GET /research?q=your+question

Timeout your HTTP client at 30 seconds minimum for /research calls. The default 5 s timeout in many HTTP libraries will fire before the response arrives.

CORS errors (browser requests)

Superhighway is a server-to-server API. Calling it directly from a browser fetch() will hit CORS restrictions. Call it from your backend (Node, Python, etc.) and proxy the result to your frontend. Do not embed API keys in client-side code.

Still stuck?

Email pat@walls.sh with the request ID from the response headers (X-Request-Id) and we'll trace it. Include the endpoint, the error body, and the approximate UTC time.