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.
Related
Something unclear or missing on this page?