Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blinkpdf.io/llms.txt

Use this file to discover all available pages before exploring further.

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 hello@blinkpdf.io 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. 
{
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
Common causes and fixes:
CauseFix
No Authorization header sentAdd Authorization: Bearer YOUR_API_KEY to every request
Typo or truncated keyCopy the key directly from your dashboard — don’t retype it manually
Key was rotatedRetrieve the new key from your dashboard and update your environment variables
Key belongs to a different environmentConfirm you’re using the key for the correct workspace (production vs. staging)
Never hardcode your API key in client-side code or commit it to a public repository. Use environment variables or a secrets manager.

​
403 Forbidden

A 403 response means your request was authenticated successfully, but it was blocked for another reason. 
{
  "error": "forbidden",
  "message": "This feature is not available on your current plan."
}
Common causes:
  • Plan limit exceeded — you’ve hit your monthly quota or daily cap (Free plan). Your quota resets at the start of your next billing period. To continue rendering immediately, upgrade your plan.
  • Spending cap reached — your configured monthly spending cap has been hit. Adjust the cap in your dashboard or wait for the next billing cycle.
  • Feature not on your plan — some API parameters (e.g., per-key attribution) require a higher-tier plan. Check the pricing page to see which plan includes the feature you need.
  • Key scoped to specific endpoints (Enterprise) — your key may have endpoint restrictions. Check your key configuration in the dashboard.

​
Rate Limit Errors

​
429 Too Many Requests

You’ll see a 429 when you exceed your plan’s sustained rate or concurrency limit. 
{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded the sustained rate limit for your plan.",
  "retry_after_seconds": 8
}
The response also includes these headers: 
Retry-After: 8
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1720000060
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. 
{
  "error": "bad_request",
  "message": "The 'content' field is required and must be a non-empty string."
}
Common causes:
  • The content field is missing, empty, or not a string
  • A required parameter (e.g., page size unit) has an invalid value
  • 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 message 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. 
{
  "error": "payload_too_large",
  "message": "Request body exceeds the 1 MB limit for your plan."
}
Per-plan limits:
PlanMax Input Size
Free256 KB
Starter1 MB
Pro2 MB
Business5 MB
Scale10 MB
EnterpriseCustom
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. 
{
  "error": "internal_server_error",
  "message": "An unexpected error occurred. Please try again or contact support if the problem persists.",
  "request_id": "req_01j9abcxyz"
}
What to do:
  1. Check the X-Request-ID response header — note the request ID. 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 hello@blinkpdf.io with your request ID and a description of the payload so the team can investigate.
A 500 error does not count against your monthly quota. 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 (Starter and above). 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 hello@blinkpdf.io with a reproducible example.

​
Performance Issues

​
Slow Renders

Blink PDF renders typically complete in ~100ms. If you’re seeing significantly longer times, 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.
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 Scale plan for priority rendering.
Free plan accounts may experience occasional cold start latency when the API hasn’t been called recently. Paid plans (Starter and above) eliminate cold starts entirely.

​
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 hello@blinkpdf.io 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.