Get a short-lived signed download URL for a document

GET 
/api/v1/documents/:id/download

Required scope: dpp:read. Returns a 2-hour signed URL to the file (Content-Disposition: attachment). The document must belong to your company — a cross-tenant or supplier-standalone document returns 404 (no existence oracle). Rate-limited per key.

Request

Responses

200

Signed URL

403

403 — missing scope (FORBIDDEN_SCOPE) or module (FORBIDDEN_MODULE).

404

Document not found / not owned (NOT_FOUND), or no file stored (NO_FILE).

429

429 — RATE_LIMITED (per-key limit, reads and writes alike; fails closed, so a limiter outage also returns 429). A limiter-down 429 is deliberately indistinguishable from a quota 429. Carries Retry-After (seconds).

Response Headers

Retry-After

Seconds to wait before retrying (429 only).

RateLimit-Limit

Per-minute request ceiling for this key's tier.

RateLimit-Remaining

Requests left in the current window (floored at 0).

RateLimit-Reset

Seconds until the window resets.

502

DOWNLOAD_FAILED, for two causes, told apart by error.message. (1) A transient storage error: safe to retry. (2) A malware-scan refusal: the document's scan status does not allow a download. A message saying the file is still being checked for malware (status Pending) can be retried later, once the check finishes, not in a tight loop. Infected and ScanFailed are NOT retryable, despite the 502 status: repeating the request returns the same refusal. Upload the file again instead. (A document that is itself Infected is answered 404 NO_FILE.)

503

503 — the API is not enabled on this environment (FEATURE_DISABLED).