Errors

Every failure uses one envelope, and every response (success or failure) carries an X-Request-Id header with the same value as request_id.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request is invalid.",
    "request_id": "req_8f2c1d",
    "retryable": false,
    "details": [
      { "path": "query.states", "code": "missing", "message": "Field required" }
    ]
  }
}

Field	Meaning
code	Stable machine-readable code. Branch on this, never on message.
message	Safe, human-readable text. Wording can change.
request_id	Quote this when you contact support.
retryable	true when repeating the same request can succeed.
details	Optional list of {path, code, message} for field errors, at most 100 entries.

When retryable is true, wait and retry with backoff. When a Retry-After header is present, wait at least that many seconds.

Codes returned by the API

Code	Status	Retryable	Meaning
INVALID_REQUEST	400	No	Malformed body, query or header, a reversed date range, too many values, a missing Idempotency-Key, or an unreadable cursor. See details.
UNSUPPORTED_FILTER	400	No	A filter code (state, product line, carrier, filing type or status) is not in the taxonomy. The search never silently widens, so fix the code.
CURSOR_QUERY_MISMATCH	400	No	The cursor was issued for a different query. Restart pagination.
INVALID_SEQUENCE	400	No	after_sequence is beyond the watcher’s high watermark.
UNAUTHORIZED	401	No	Missing, invalid, revoked, expired or wrong-environment key.
FORBIDDEN	403	No	The key is valid but not entitled to the requested data.
NOT_FOUND	404	No	The filing, version, document or watcher does not exist, or is outside your entitlements.
SOURCE_UNAVAILABLE	404	No	The version exists but its source documents are not available, so there is no manifest or download.
IDEMPOTENCY_CONFLICT	409	Only while the original is in progress	The Idempotency-Key was already used with a different body. When the original request is still running the response is marked retryable.
CLIENT_REFERENCE_CONFLICT	409	No	The client_reference already belongs to a watcher with a different definition. References are never reused, even after deletion.
CONFLICT	409	Yes	Sandbox only: POST /test/detection:run while a change-detection pass is already running. Retry after a few seconds, or let the scheduled pass pick up your change. See Environments.
CURSOR_EXPIRED	410	No	The cursor is older than 30 minutes. Restart pagination.
REPLAY_WINDOW_EXPIRED	410	No	The next event you need was purged (events are kept 30 days). Reconcile from search, then resume.
VERSION_SUPERSEDED	410	No	Manifests and downloads exist only for a filing’s current version. Read the filing again for its latest version.
PRECONDITION_FAILED	412	No	If-Match does not match the watcher’s current revision. Read the watcher and try again.
PAYLOAD_TOO_LARGE	413	No	The request body is over the route’s size limit.
CAPABILITY_UNSUPPORTED	422	No	The operation is not possible in this state, for example changing a deleted watcher, or a version above the manifest size limits.
WATCHER_LIMIT_REACHED	422	No	The account already has 100 active or paused watchers.
WATCHER_SCOPE_TOO_BROAD	422	No	A query watcher matches more than 25,000 filings. Narrow the filters.
PRECONDITION_REQUIRED	428	No	PATCH /watchers/{watcher_id} needs an If-Match header.
RATE_LIMITED	429	Yes	Over the per-minute request limit, too many concurrent download issuances, or (sandbox) more than one POST /test/detection:run per account in 30 seconds. See Retry-After.
INTERNAL	500	Yes	Unexpected server error. Retry with backoff and quote the request_id if it persists.
SERVICE_UNAVAILABLE	503	Yes	A dependency is temporarily unavailable. Retry after the Retry-After delay.

Codes that are not API responses

Code	Where	Meaning
INVALID_SIGNATURE	Your webhook receiver	The code your receiver returns (with status 401) when a delivery’s signature is wrong or its timestamp is stale. See Webhooks.
DESTINATION_REJECTED	Delivery log	A webhook delivery was stopped because the destination URL failed safety checks (not HTTPS, not port 443, resolves to a private or metadata address, or redirected). No request is sent to that address. It appears in the delivery log in the admin area, not in an HTTP response.

Handling errors

import os
import time

import httpx

BASE = "https://api.dev.velocifile.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['VELOCIFILE_API_KEY']}"}


def call(method: str, path: str, attempts: int = 5, **kwargs) -> httpx.Response:
    for attempt in range(attempts):
        response = httpx.request(method, f"{BASE}{path}", headers=headers, timeout=30, **kwargs)
        if response.status_code < 400:
            return response
        error = response.json()["error"]
        if not error["retryable"] or attempt == attempts - 1:
            raise RuntimeError(f"{error['code']} ({error['request_id']}): {error['message']}")
        delay = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(delay)
    raise AssertionError("unreachable")


print(call("GET", "/taxonomies", params={"limit": 1}).status_code)