Errors return JSON, with the status repeated in the body:
{
"message": "parameter \"keywordSearch\" is not supported in v1; deferred to v2",
"status": 400
}
| Status | Meaning | What to do |
|---|---|---|
400 | Invalid parameter, malformed date range, malformed cursor, or a v1-deferred parameter | Read message — it distinguishes a deferred parameter from a typo. Do not retry unchanged |
401 | Missing or invalid credentials | Check the apiKey or Authorization header |
403 | Authenticated, but not entitled to this resource | Contact VulnCheck about your entitlement |
404 | Unknown path | Check the endpoint spelling against the mapping table |
405 | Method not allowed | These endpoints are GET only |
429 | Rate limit exceeded | Back off for the number of seconds in Retry-After |
503 | Service temporarily unavailable | Retry with exponential backoff |
NVD has a very restrictive rate limit so we aligned ours to the much more expansive 1,000 requests per minute per token e.g., the same community API rate limit that applies to the rest of the VulnCheck API. There is no separate, stricter budget for these endpoints.
That is twenty times NVD's own cap of 50 requests per 30 seconds, so a client that was pacing itself against NVD's limit will stay comfortably inside this one without changing anything.
NVD's unauthenticated tier of 5 requests per 30 seconds has no equivalent here: every request needs valid credentials, so there is no anonymous bucket to fall into.
A 429 carries a Retry-After header with the number of seconds to wait:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json
{ "message": "rate limit exceeded", "status": 429 }
X-RateLimit-* headers are not emitted. NVD does not document any either, so a client written against NVD will not be looking for them. Use Retry-After on a 429.resultsPerPage defaults to the endpoint maximum, so one large request costs the same against the budget as one small one./v3/backup/{index} rather than paging (one download instead of hundreds of requests).lastModStartDate and lastModEndDate for incremental syncs instead of re-walking everything.