Response headers

Every response header gpdf-api sets, what it means, and which endpoints emit it.

Response headers

Every gpdf-api response carries a few metadata headers. Keep an eye on the quota and rate-limit ones — they let you track quota in-band without any extra requests.

Always set

Header Example Notes
X-Request-Id req_01HZTV... Server-issued trace ID. Quote when filing an issue.
Server-Timing body_read;dur=0.4, json_parse;dur=0.6, render;dur=12.8, total;dur=13.9 Stage-level timings in milliseconds. Set on every request handled by /v1/pdf.

Set on POST /v1/pdf (success)

Header Example Notes
Content-Type application/pdf Always this on 200.
Content-Disposition attachment; filename="invoice.pdf" Reflects options.filename. Omitted when no filename is provided.
Content-Length 12345 Bytes of the PDF body.
X-GPDF-Pages 3 Number of pages in the PDF.
X-GPDF-Latency-Us 13872 Render time, microseconds (int64). UI should auto-pick µs/ms/s.
X-GPDF-Quota-Limit 10000 Plan + addon limit for this period.
X-GPDF-Quota-Remaining 8749 Successful renders left.
X-GPDF-Quota-Reset 2026-05-01T00:00:00Z RFC 3339, UTC.
X-GPDF-RateLimit-Limit 40 Burst capacity of the per-key token bucket.
X-GPDF-RateLimit-Remaining 37 Tokens left right now.
X-GPDF-RateLimit-Reset 1714234567 Unix timestamp (seconds) when the next token arrives.

X-GPDF-Latency-Us is the server-side render time only. It does not include network or auth time. If you want end-to-end, measure on your side.

The response body is always raw PDF bytes — Content-Encoding is never set. PDF streams are already DEFLATE-compressed inside the file, so transport-level gzip would add CPU cost for negligible savings.

Set on errors

JSON error responses carry the same X-Request-Id header, plus:

Header Example Notes
Content-Type application/json; charset=utf-8 Errors are JSON, never PDF.
Retry-After 1 (seconds) Set on 429 and on quota-exceeded 402s.

Deprecation headers

When you call something we plan to remove:

Header Example Notes
Deprecation true Sent when an endpoint or field is deprecated.
Sunset Wed, 01 Oct 2026 00:00:00 GMT The date after which the call may stop working.
Link <https://docs.gpdf.dev>; rel="deprecation" Where to read about the replacement.

We give at least 90 days between the first Deprecation header and the Sunset date.

CORS

The gpdf-api allows cross-origin requests from any origin (Access-Control-Allow-Origin: *) for the public /health endpoint. The production /v1/pdf endpoint requires an Authorization header and so is not CORS-friendly from a browser — that's intentional. Don't put your raw API key in front-end code.

Something unclear or missing on this page?