Skip to main content
This guide covers the most common issues you might encounter when integrating with the Blink PDF API, with clear explanations and steps to resolve each one. If you work through the relevant section and still can’t resolve the problem, email [email protected] with your request ID and we’ll take a look.

​
Authentication Errors

​
401 Unauthorized

You’ll receive a 401 when the API cannot verify your identity.
Common causes and fixes:
Never hardcode your API key in client-side code or commit it to a public repository. Use environment variables or a secrets manager.

​
402 Payment Required

A 402 response means your request was authenticated successfully, but your plan’s spend cap has been reached on a metered PDF route (POST /v1/render or POST /v1/templates/*/render). Usage beyond the included volume is paused until the next billing period.
Common causes:
  • Plan limit reached — you’ve used all your render units for the period, or hit your plan’s hard cap (2× the included volume). Your allowance resets at the start of your next billing period. To continue rendering immediately, upgrade your plan. There is no daily cap on any plan.
  • Spending cap reached — your configured spending cap has been hit. Raise the cap in your dashboard or wait for the next billing cycle.

​
404 Not Found

A 404 means the request did not match any registered route (for example a typo in the path). Matched operations such as POST /v1/render never return this status when the path is correct.
How to fix it:
  • Confirm the path is exact (e.g. /v1/render, not /v1/renders or /render)
  • Confirm the HTTP method is allowed on that path (wrong methods return 405, not 404)
  • Use the discovery document at GET / or the API overview for the current public surface

​
Rate Limit Errors

​
429 Too Many Requests

You’ll see a 429 when you exceed your plan’s sustained rate or concurrency limit.
The response also includes a Retry-After header:
How to handle it:
  1. Read the Retry-After header — this is the minimum number of seconds to wait before retrying.
  2. Implement exponential backoff with jitter so that multiple clients don’t retry in lockstep.
  3. If you’re consistently hitting 429, consider:
    • Spreading requests more evenly over time using a queue
    • Raising the concurrency in your client up to (but not exceeding) your plan’s concurrency limit
    • Upgrading to a plan with a higher rate limit
On Pro (10 concurrent) or Business (40 concurrent), pipelining renders up to your concurrency limit is usually more effective than increasing per-minute throughput.

​
Request Errors

​
400 Bad Request

A 400 means the API understood your request but found something wrong with the payload.
Common causes:
  • The markdown field is missing or not a string
  • A field has an invalid value (e.g., a margin outside the 0–2880 point range, or a fontStack that breaks the composition rules)
  • Malformed JSON in the request body — check your Content-Type: application/json header
  • An unsupported Markdown extension or syntax that the parser cannot process
Check the error detail field — it usually identifies the specific field or value that failed validation.

​
413 Payload Too Large

Your request body exceeds the maximum input size for your plan.
Per-plan limits: How to fix it:
  • Split very large documents into multiple render calls and combine the PDFs client-side if needed
  • Remove large embedded base64 assets from the payload and reference them as external URLs instead
  • Upgrade your plan to access a higher input size limit
The size limit applies to the request body, not the output PDF. A document that compresses well in Markdown may produce a larger PDF, and that’s fine.

​
Server Errors

​
500 Internal Server Error

A 500 response means something went wrong on Blink PDF’s side — your request was valid, but the server encountered an unexpected condition while processing it.
What to do:
  1. Check the X-Request-Id response header — note the request ID (a UUID). You’ll need it if you contact support.
  2. Retry with exponential backoff — transient server errors often resolve within seconds. Use the same retry logic as for 429 responses, but limit to 2–3 attempts.
  3. Check the status page — if you’re seeing widespread 500 errors, visit status.blinkpdf.io to see if there is an active incident.
  4. Contact support — if 500 errors persist across retries and no incident is posted, email [email protected] with your request ID and a description of the payload so the team can investigate.
A 500 error does not consume render units. If a render fails server-side, you are not charged for that request.

​
Render Quality Issues

​
Watermark Appearing on PDFs

Watermarks are added automatically on the Free plan. This is expected behavior and cannot be disabled at the Free tier. To remove watermarks: Upgrade to any paid plan (Pro or Business). Watermarks are removed immediately — you don’t need to change anything in your API request.

​
PDF Not Accessible / Fails Accessibility Check

All Blink PDF output is PDF/UA-1 compliant by default. If you’re running an accessibility validator and seeing failures, check the following:
  • Confirm you’re testing the PDF returned directly by the API, not a version that was post-processed by another tool (e.g., a PDF editor or merger that strips accessibility metadata)
  • If you’re embedding PDFs into a larger document using a third-party library, ensure that library preserves the accessibility tagging from Blink PDF’s output
  • Check that your Markdown uses semantic structure (proper heading levels, alt text on images) — while Blink PDF handles the technical PDF/UA tagging, meaningful document structure starts with your content
If you believe accessibility output from the API itself is incorrect, contact [email protected] with a reproducible example.

​
Performance Issues

​
Slow Renders

Blink PDF is designed for low-latency Markdown rendering. If a render takes longer than expected, consider these factors:
When your Markdown includes images referenced by URL (e.g., ![chart](https://example.com/chart.png)), Blink PDF must fetch each image over the network before completing the render. Network latency and the response time of the remote server add directly to your total render time.Fix: Host images on a fast CDN, reduce the number of remote images, or embed images as base64 data URIs if they’re small and static. For repeat renders of the same request, set pinRemoteImages: true to reuse each image’s bytes for up to 24 hours — later renders skip the re-fetch and stay byte-identical.
Documents with many pages, dense typography, or numerous embedded assets take longer to lay out and encode. This is expected — render time scales with document complexity.Fix: For very large documents, consider whether you can render them in sections and merge the output, or move to a Business or Enterprise plan for priority rendering.
The first request you send from a new environment can include extra network or routing latency before the render starts. If latency stays high across repeated requests, check the factors above or contact support with a request ID.

​
Still Stuck?

If you’ve worked through the relevant sections above and the issue persists, we’re happy to help directly.

Email Support

Send a message to [email protected] with your request ID (found in the X-Request-Id response header), a description of the issue, and a minimal reproducible example if possible. We’ll investigate and get back to you.
Business plan customers also have access to a dedicated Slack support channel — check your welcome email for the invite link.