Error codes
Every error gpdf-api can return — when, what it means, and the fix.
Error codes
Every error response shares the same envelope:
{
"error": {
"code": "rate_limited",
"message": "Too many requests for this key. Retry after 1.0s.",
"request_id": "req_01HZTV...",
"doc_url": "https://docs.gpdf.dev/errors/rate_limited"
}
}
code is stable; message is human-readable and may improve over time. Always switch on code, never on message.
At a glance
| HTTP | code |
Retry? |
|---|---|---|
| 400 | invalid_request |
No |
| 400 | template_error |
No |
| 400 | otp_required |
No |
| 401 | unauthorized |
No |
| 402 | quota_exceeded |
No (until reset / addon) |
| 403 | forbidden |
No |
| 403 | otp_not_verified |
No |
| 404 | not_found |
No |
| 409 | account_exists |
No |
| 413 | payload_too_large |
No |
| 413 | response_too_large |
No |
| 429 | rate_limited |
Yes — honour Retry-After |
| 500 | internal_error |
Yes (1 retry) |
| 503 | service_unavailable |
Yes — exponential backoff |
Validation (400)
invalid_request
The top-level fields are wrong: missing template, malformed slug, unknown option key, malformed JSON, wrong type. Also returned when query parameters or path segments fail validation (e.g. malformed pagination cursor, label longer than 64 bytes on POST /v1/account/keys).
{ "error": { "code": "invalid_request",
"message": "invalid 'slug': only [A-Za-z0-9._-] are allowed" } }
Fix: Read the message; it includes the offending field.
template_error
The template parsed but failed to lay out. Examples: unknown node type, span totalling > 12, malformed Go-template tag, image fetch failure.
{ "error": { "code": "template_error",
"message": "table column spans sum to 14 (max 12) at body[3].table.columns" } }
Fix: Validate against the Document schema. Most production teams add a JSON-schema check on their side before calling the API.
otp_required
Returned by POST /v1/auth/signup when the Firebase user authenticated through a password provider but did not include a verified one-time password in the request body.
Fix: Call POST /v1/auth/otp/send, then POST /v1/auth/otp/verify, and pass the verified otp value when retrying signup.
Auth (401, 403)
unauthorized
Authentication failed. This single code covers all of: missing Authorization header, malformed Bearer value, API key that does not exist or has been revoked, and Firebase ID token that is expired / signed by the wrong issuer / for the wrong project.
Fix: Check the header value. For API keys, create a new one if the old one was revoked. For Firebase tokens, refresh client-side and retry once.
forbidden
The key/token authenticated but doesn't have access to the resource. E.g. calling /v1/pdf with a license key (license keys can't render).
Fix: Use the right credential type. See Authentication.
otp_not_verified
Signup-flow only. The OTP code wasn't sent or is expired.
Fix: Re-issue the OTP via POST /v1/auth/otp/send.
Resource (404, 409)
not_found
The path is right but the resource doesn't exist on this account. E.g. DELETE /v1/account/keys/gpdf_xxx where that prefix doesn't belong to you.
Fix: Check the resource ID. We deliberately return 404 instead of 403 here so that we don't leak the existence of resources owned by other accounts.
account_exists
Signup with a Firebase user that already has an account. Use sign-in instead.
Fix: POST /v1/auth/signin.
Quota (402)
quota_exceeded
You've used all your monthly successful renders.
{ "error": { "code": "quota_exceeded",
"message": "Monthly quota of 10000 (Pro) exhausted. 1247 attempts since reset." } }
Fix: Buy an addon pack, upgrade your plan, or wait until the next billing reset (1st of the month, UTC).
The response also includes X-GPDF-Quota-Reset so you can show "Resets in 4 days" to your users.
Size (413)
payload_too_large
The request body (after gzip decoding) is over 8 MiB.
Fix: Trim data. If you really need that much input, split the render into chunks.
response_too_large
The rendered PDF would exceed your plan's response cap (5 MB Free / 15 MB Pro / ∞ Self-host).
{ "error": { "code": "response_too_large",
"message": "Generated PDF (7.2 MB) exceeds Free plan limit of 5 MB. Upgrade to Pro for 15 MB." } }
Fix: Compress embedded images (JPEG, not PNG, for photos), use vector logos, split the document.
Rate (429)
rate_limited
Per-key bucket exhausted, or sandbox per-UID 5 r/s exhausted. Response includes:
Retry-After: 1
Fix: Wait Retry-After seconds and retry. Don't tighten your retry loop — exponential backoff is the right answer.
See Rate limits.
Server (500–504)
internal_error
A bug. The request_id lets us look up the exact failure trace.
Fix: One retry is fine — sometimes it's a transient server-side issue. If it persists, report the request_id to support and stop retrying.
service_unavailable
A downstream dependency (Firestore, Polar) is misbehaving. Status page link in the error body.
Fix: Retry with exponential backoff (1, 2, 4, 8 s). If you're seeing this in volume, check the status page.
Retry policy summary
2xx → return result
4xx (except 429) → don't retry — fix the request
429 → wait Retry-After, then retry
5xx → exponential backoff up to 4 attempts
Note — gpdf-api does not currently surface a separate
timeoutcode; long-running renders that exceed the server deadline come back asinternal_errorwith therequest_idto track them down.
Related
Something unclear or missing on this page?