Skip to content

VDB API troubleshooting

The VDB API and vulnetix vdb errors you are most likely to see, what causes each one and how to fix it, including answers that look wrong but are not errors.

Updated 04 Nov 2026Markdown

The API answers errors as JSON with an error field. The CLI prints them as Error: API error (<status>): <error> on stderr and exits 1; the full list of statuses is on Errors and plan-gated answers.

Credentials

Symptom or message Cause Fix
401 Invalid API key from curl, while the CLI works The header carries the org id twice: ApiKey <org>:<org>:<hex>. The Resolve Platform shows the key as <orgId>:<hex> already Put only the hex part in VULNESIS_API_KEY, or paste the Resolve Platform value straight after ApiKey . See Authentication
401 Invalid API key everywhere The secret was regenerated on the Account page, so the old HMAC no longer matches Copy the new key from the Account page
401 Malformed ApiKey header. Expected: Authorization: ApiKey <orgId>:<sha256-hex> No : in the value, or one half is empty Check the variables are set: an unset VULNESIS_ORG_ID leaves ApiKey :<hex>
401 Token has expired. Please obtain a new token from /v1/auth/token. A JWT older than 15 minutes Fetch a new one from GET /v2/auth/token. There is no refresh token. The CLI does this itself for SigV4
Auth: Unauthenticated Community (run 'vulnetix auth login' for higher rate limits) with -v No credential was found, so the CLI used the shared built-in Community key Sign in, or set the variables. Which source wins is on CLI flags, output and cache and Troubleshooting authentication

Quota and retries

Symptom or message Cause Fix
429 Daily rate limit exceeded with Limit: 50 requests per day. Resets in 7 hours. The key used its quota for the rolling 24 hours Wait, or move to a plan with more requests. Pace against RateLimit-Remaining. See Rate limits
Quota is still gone after the RateLimit-Reset time The window is a rolling 24 hours; RateLimit-Reset always quotes the next 00:00 UTC Count from when the requests were made, not from the header
A vdb command waits for minutes or hours, showing a rate-limit countdown on stderr On a 429 the CLI waits for Retry-After, otherwise RateLimit-Reset Run the CLI under a timeout in CI. -v also prints each retry
request failed after 2 retries: HTTP 503 authentication backend temporarily unavailable or maintenance mode, still failing after two retries Try again later. The key is not invalid. Maintenance refuses writes only; see Maintenance mode

Results look wrong

Symptom Cause Fix
⚠ Vulnerability "<id>" was not found in the database. The API answered 404 for that id Check the spelling against Identifiers and inputs. URL-encode ids with : or / in curl paths
Fields are null and the answer has _pro_data or _entitlements, or the body is {"planLocked": true, ...} Those fields, or the whole route, need a higher plan. It is a 200, not an error Read _entitlements.gated for the plan each one needs. See Plan-gated answers
An answer is stale The CLI’s disk cache answered --refresh-cache for one call, or vulnetix vdb cache clear. See Local cache
vdb exploits poc or vdb exploits download fails with API error (404): {"error":"Package not found", ...} The CLI asks for a route the API does not serve Use the /archive route with curl. See vulnetix vdb commands
vdb triage always prints an empty feed The triage endpoint the CLI calls first returns no items yet Query GET /v2/triage directly
Reachability reports nothing The v2 reachability route is not served, and the CLI reads the not-found as “no queries” Pass --reachability off to skip the call

Still stuck

Collect the CLI version from vulnetix version, the exact command, and its output with -v (or -vv for raw evidence), which shows the plan, the remaining quota and the credential source. Add vulnetix auth status and, for curl, the status line and the response headers (curl -sS -D - -o /dev/null ...) with the key removed. For credential problems, work through Troubleshooting authentication first.

esc
↑ ↓ move↵ openSearches in your browser. A key like autonomy.max or a code like threshold_required jumps straight to it.