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 timeout code; long-running renders that exceed the server deadline come back as internal_error with the request_id to track them down.

Something unclear or missing on this page?