> ## 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. # Blink PDF Troubleshooting: Fix API Errors & Render Issues > Fix common Blink PDF integration issues — from 401 auth errors and 429 rate limits to watermarks, slow renders, and payload size problems. 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 [support@blinkpdf.io](mailto:support@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. ```json theme={null} { "error": "unauthorized" } ``` **Common causes and fixes:** | Cause | Fix | | -------------------------------------- | ----------------------------------------------------------------------------------------------------- | | No `x-api-key` header sent | Add `x-api-key: bp_xxxxxxxxxxxxxxxxxxxx` to every authenticated render or template request | | Typo or truncated key | Copy the key directly from your [dashboard](https://app.blinkpdf.io/login) — don't retype it manually | | Key was rotated | Retrieve the new key from your dashboard and update your environment variables | | Key belongs to a different environment | Confirm 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. *** ### 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. ```json theme={null} { "error": "spend_cap_reached", "detail": "The monthly spend cap for this plan has been reached. Usage that exceeds the included volume is paused until the next billing period. Raise the spend cap or upgrade the plan to continue." } ``` **Common causes:** * **Plan limit reached** — you've used all your [render units](/plans/pricing#how-billing-works-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. ```json theme={null} { "error": "not_found" } ``` **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](/api-reference/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. ```json theme={null} { "error": "rate_limited", "detail": "You have exceeded the sustained rate limit for your plan." } ``` The response also includes a `Retry-After` header: ``` Retry-After: 8 ``` **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. ```json theme={null} { "error": "validation_failed", "detail": "The 'markdown' field is required and must be a string." } ``` **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. ```json theme={null} { "error": "payload_too_large", "detail": "Request body exceeds the maximum allowed size." } ``` **Per-plan limits:** | Plan | Max Input Size | | ---------- | -------------- | | Free | 128 KB | | Pro | 2 MB | | Business | 5 MB | | Enterprise | Custom | **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. ```json theme={null} { "error": "internal_error", "detail": "An unexpected error occurred. Please try again or contact support if the problem persists." } ``` **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](https://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 [support@blinkpdf.io](mailto:support@blinkpdf.io) 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 [support@blinkpdf.io](mailto:support@blinkpdf.io) 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`](/configuration/document-options#the-pinremoteimages-field) 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. Geographic distance between your application server and the Blink PDF API can add network latency that's unrelated to render time. **Fix:** Deploy your application in a region geographically close to the Blink PDF API. Enterprise customers can discuss regional deployments to minimize this latency. 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. Send a message to **[support@blinkpdf.io](mailto:support@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.