Rate limits

Each key gets 60 requests per minute by default. The limit is a fixed one-minute window per key and can be raised per account by VelociFile. Separately, each key can have 10 download issuances in flight at once.

Headers

Every successful response carries the current state of your window:

Header	Meaning
RateLimit-Limit	Requests allowed per window for this key.
RateLimit-Remaining	Requests left in the current window.
RateLimit-Reset	Seconds until the window resets, between 1 and 60.

HTTP/1.1 200 OK
RateLimit-Limit: 60
RateLimit-Remaining: 41
RateLimit-Reset: 23
X-Request-Id: req_...

When you exceed the limit

The response is 429 with code RATE_LIMITED, retryable: true, the same three headers and an integer Retry-After in seconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 23
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 23

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after the indicated delay.",
    "request_id": "req_...",
    "retryable": true
  }
}

Wait at least Retry-After seconds, then retry. Do not retry in a tight loop.

Concurrent downloads

Issuing a download URL (.../documents/{document_id}/download) counts against a separate limit of 10 issuances in flight per key. Over it, you get 429 RATE_LIMITED with Retry-After: 1. Fetching the PDF from the issued URL does not count. Download in a bounded worker pool of 10 or fewer.

Staying under the limit

• Use limit=100 on list calls and page instead of making many small calls.
• Use watchers instead of polling search for changes.
• Spread bulk downloads over time, and respect RateLimit-Remaining.
• Cache taxonomies. They change rarely and carry a taxonomy_version.