How to PDF API Error Handling
Robust error handling is the difference between a production PDF service that recovers gracefully and one that drops documents silently. SublimePDF's API uses standard HTTP status codes and structured JSON error responses so your application can diagnose failures, retry safely, and present meaningful messages to end users.
Follow the step-by-step instructions below, then use the free tool directly — no registration or download required.
Open Tool →How to PDF API Error Handling — Step by Step
Understand the HTTP status code categories
2xx means success: the PDF was generated. 4xx means client error: your request has a problem (bad parameters, invalid template, authentication failure). 5xx means server error: something went wrong on SublimePDF's side and the request should be retried.
Parse the error response body
All error responses return JSON with three fields: 'error' (machine-readable code like 'invalid_template'), 'message' (human-readable explanation), and optionally 'details' (an array of specific validation issues). Always log the full response body.
Handle common 4xx errors
400 Bad Request: malformed JSON or missing required fields. 401 Unauthorized: invalid or missing API key. 403 Forbidden: key lacks required scope. 404 Not Found: invalid template ID or endpoint. 422 Unprocessable Entity: the template rendered but produced invalid output (e.g., LaTeX compilation error).
Implement retry logic for 5xx and 429
429 Too Many Requests: you've exceeded rate limits — read the Retry-After header and wait. 500/502/503: transient server issues — retry with exponential backoff (1s, 2s, 4s, 8s) up to 3–5 attempts. Never retry 4xx errors without changing the request.
Add monitoring and alerting
Track error rates by status code in your application metrics (Datadog, New Relic, CloudWatch). Alert when 4xx errors spike (indicates a deployment broke your request format) or when 5xx errors persist (indicates an API outage).
Pro Tips
- 💡 Always check the Content-Type header before parsing the response — successful requests return application/pdf, while errors return application/json. Attempting to parse a PDF binary as JSON will crash your code.
- 💡 Include the X-Request-Id from the error response in your logs and support tickets — SublimePDF's team can look up exactly what happened for that request.
- 💡 Wrap your PDF generation calls in a try-catch that distinguishes between network errors (no response received) and API errors (response received with error status) — they require different handling strategies.
- 💡 For 422 errors on template rendering, the 'details' field often contains the exact line number and error in the template. Pipe this to your logging system for fast debugging.
Privacy & Security
All processing happens directly in your browser. Your files are never uploaded to any server — they remain on your device throughout the entire process. SublimePDF uses WebAssembly technology for fast, secure, client-side processing.
Works Everywhere
This tool works on any modern browser — Chrome, Firefox, Safari, or Edge — on desktop, tablet, or mobile. No software to install. PDF is an open ISO standard supported by all major platforms.
How to PDF API Error Handling — FAQ
What does a 429 Too Many Requests error mean?
Should I retry on 400 Bad Request?
How can I tell if an error is transient or permanent?
Does the API return errors in the PDF itself?
Related Guides
How to PDF API Authentication
Every API request to SublimePDF requires authentication via an API key. Proper authentication keeps your account secure, prevents unauthorized PDF generation, and ensures your usage is correctly tracked. This guide covers how to generate keys, include them in requests, rotate credentials, and handle authentication errors.
How to PDF API Rate Limits
Rate limits protect the SublimePDF API from abuse and ensure fair resource allocation across all users. Understanding your plan's rate limits, monitoring your usage, and implementing proper throttling prevents disruptions in your PDF generation workflow. This guide explains rate limit tiers, response headers, and strategies for staying within limits.
How to Convert HTML To PDF
Converting HTML to PDF is a core workflow for developers, marketers, and anyone who needs a permanent, printable snapshot of web content. Whether you're archiving a webpage, generating reports from a web app, saving receipts from online purchases, or creating documentation from HTML templates, PDF conversion captures the visual layout, links, and styling in a portable format.