Troubleshooting

Every error response is JSON with an error field. Match the status code below to find the fix.

`401 unauthorized`

{ "error": "unauthorized", "message": "Invalid API key.", "signupUrl": "https://viralquery.com" }

The key is missing, malformed, or revoked.

Send the header exactly as Authorization: Bearer sk_viralquery_... — the Bearer prefix is required.
Confirm you copied the whole key. It's shown once at signup; if you lost it, get a new one via Get an API key.
"Session key expired." means a short-lived sandbox key timed out — start a fresh /v1/agent run.

`403 forbidden`

{ "error": "forbidden", "requiredScope": "library:search", "grantedScopes": ["library:browse"] }

Your key is valid but scoped to a narrower set of ops than the one you called. The body names the scope the op needs and the scopes the key has. Use a key whose scopes include the required pattern ("*", "library:*", or the exact library:search), or mint a new one with broader scopes. See Authentication.

`402 Payment Required`

You're out of credits. The body carries required, balance, and a topupUrl. Top up with POST /v1/topup — full details in Credits & billing.

`429 rate_limited`

{ "error": "rate_limited", "message": "Too many requests." }

You exceeded the per-minute request cap. The response includes a Retry-After header (seconds) — wait that long and retry. Back off exponentially if you're running a tight loop.

Empty search or browse results

{ "results": [] }

A 200 with an empty list is not an error — the query simply matched nothing. Common causes:

Filters too narrow. Drop the platform / category filters on /v1/library/browse and widen the query on /v1/library/search (it ranks by meaning, so broader phrasing returns more).
The library hasn't been populated yet. A freshly deployed instance starts empty; the operator ingests viral videos before results appear. If you're the operator, see the ingestion ops under admin and confirm SCRAPE_CREATORS_API + GOOGLE_GENERATIVE_AI_API_KEY are set.

The get endpoint is GET /v1/library/videos; a 404 there means that specific video id isn't in the library.

Agent ("ask") run fails

POST /v1/agent drives an LLM loop over the sandbox. If it errors before doing work, the 50-credit orchestration fee is refunded automatically — you only pay for runs that succeed.

"Unable to reach the model." The operator hasn't set the AI Gateway key (AI_GATEWAY_API_KEY) on the deployment. Browse and search still work without it; only the agent surface needs it.
Sandbox errors mid-run. The agent runs code in a per-call sandbox with the SDK pre-injected. Transient sandbox failures are surfaced in the output; retry the goal, and consider lowering maxSteps (1–25) to bound cost.

After POST /v1/signup you poll POST /v1/signup/claim with the claimToken:

pending — the Stripe payment hasn't completed yet. Finish checkout at the returned url, then poll again.
already_claimed — the key was already minted and shown. Keys are returned once; if you didn't capture it, sign up again.
invalid_token — the token is wrong or expired.

Still stuck?

Call GET /v1/balance (a free op) to confirm your key authenticates and check your remaining credits — it's the fastest way to isolate an auth problem from a billing one.

On this page