PDFShift API Authentication Error 401: How to Fix It
Fix PDFShift 401 errors by checking the current X-API-Key header, testing credentials with the credits endpoint, and retrying conversion correctly.
If PDFShift returns 401 Unauthorized, first confirm that your request sends the API key in the X-API-Key HTTP header. PDFShift changed from its older Basic Auth mechanism to this header on 2025-05-06. Then test the same key against the credits endpoint before retrying PDF conversion.
1. Check the authentication method
PDFShift’s current authentication header is X-API-Key. The key itself is the header value:
X-API-Key: YOUR_API_KEYPDFShift states that it moved to the X-API-Key header on 2025-05-06. If your client is still configured to send only the older Basic Auth credentials, replace that configuration with the header. A missing or incorrectly sent key can result in 401 or 403; PDFShift does not publish a definitive mapping of each specific mistake to one status code. See the PDFShift Help Center authentication guidance.
2. Test the key with the credits endpoint
Make a GET request to https://api.pdfshift.io/v3/credits/usage using the same header you intend to use for conversion. PDFShift says an authenticated response includes usage and available-credit data. If this diagnostic returns 401 or 403, focus on how the request sends the key before troubleshooting the conversion payload.
cURL
curl -i \
-H "X-API-Key: YOUR_API_KEY" \
https://api.pdfshift.io/v3/credits/usageThe -i flag prints response headers along with the body, which helps confirm the status while diagnosing the request.
Python
import requests
api_key = "YOUR_API_KEY"
response = requests.get(
"https://api.pdfshift.io/v3/credits/usage",
headers={"X-API-Key": api_key},
timeout=30,
)
print(response.status_code)
print(response.text)Node.js
const apiKey = "YOUR_API_KEY";
const response = await fetch(
"https://api.pdfshift.io/v3/credits/usage",
{ headers: { "X-API-Key": apiKey } }
);
console.log(response.status, await response.text());3. Retry the PDF conversion
Once the diagnostic request authenticates, make the conversion request separately. PDFShift’s Python and Node guides put X-API-Key in the request headers for a POST to https://api.pdfshift.io/v3/convert/pdf.
cURL conversion example
curl -i \
-X POST "https://api.pdfshift.io/v3/convert/pdf" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"source":"https://example.com"}' \
-o output.pdfThis writes the response body to output.pdf. During diagnosis, inspect the status and response body; a saved file alone does not tell you whether the request succeeded.
Python conversion example
import requests
api_key = "YOUR_API_KEY"
response = requests.post(
"https://api.pdfshift.io/v3/convert/pdf",
headers={"X-API-Key": api_key},
json={"source": "https://example.com"},
timeout=90,
)
print(response.status_code)
if response.ok:
with open("output.pdf", "wb") as pdf_file:
pdf_file.write(response.content)
else:
print(response.text)Node.js conversion example
const apiKey = "YOUR_API_KEY";
const response = await fetch(
"https://api.pdfshift.io/v3/convert/pdf",
{
method: "POST",
headers: {
"X-API-Key": apiKey,
"Content-Type": "application/json",
},
body: JSON.stringify({ source: "https://example.com" }),
}
);
console.log(response.status);
if (response.ok) {
const pdf = Buffer.from(await response.arrayBuffer());
await import("node:fs/promises").then(({ writeFile }) =>
writeFile("output.pdf", pdf)
);
} else {
console.error(await response.text());
}For the provider’s original client patterns, see the PDFShift Python guide and PDFShift Node guide.
4. Check workflow and client configuration
Some HTTP clients have an authentication selector that can add or replace headers. Make sure the final outbound request contains X-API-Key with the intended key. In PDFShift’s n8n instructions, the HTTP Request node uses the conversion URL and POST method, the authentication selector stays at None, and the API key is added as a request header. Follow the PDFShift n8n guide for that workflow.
- Check the exact header name:
X-API-Key. - Check that the header value is the key, not a Basic Auth username/password pair.
- Check that the library or workflow actually sends the configured header on the request.
- When using a workflow tool, avoid enabling a separate authentication mode that changes the outgoing request.
- Do not paste a live key into public logs, screenshots, or source control. Use your environment’s secret storage where available.
5. Troubleshooting common outcomes
| Symptom | Likely request issue | What to check |
|---|---|---|
| 401 from credits/usage | The diagnostic request did not authenticate. | Inspect the outbound request for X-API-Key and verify its value is being sent as a header. |
| 403 from credits/usage | PDFShift says authentication-related mistakes can result in 403 as well as 401. | Check the same header and value; the available provider guidance does not define a precise cause for each status. |
| Diagnostic succeeds, conversion fails | The key was accepted by the diagnostic endpoint, but that alone does not establish why conversion failed. | Inspect the conversion response status and body, then review the conversion URL, method, and request payload separately. |
| Works in a script but fails in a workflow | The workflow may not be sending the header as configured. | Set the API key as a request header. In the documented n8n setup, leave its authentication selector at None. |
| Old integration suddenly returns an auth error | It may still rely on the former Basic Auth method. | Update the request to use X-API-Key, the method PDFShift documents after its 2025-05-06 change. |
Do not infer a particular account state, key revocation, or key lifecycle event from the status alone: the cited PDFShift materials do not establish those as the cause of an individual 401 or 403.
Or skip the browser setup
If your goal is to capture a web page as an image rather than convert it to PDF, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpPython:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, no card required.
Performance, reliability, and cost considerations
For this authentication problem, the credits/usage GET is a narrow diagnostic: it separates credential transmission from conversion behavior without requiring a PDF conversion request. If it succeeds, retry conversion and handle its response independently. Set a suitable client timeout for conversion requests; the Python example uses 90 seconds, while the short diagnostic uses 30 seconds. These are client-side example values, not PDFShift service guarantees.
The supplied research does not document PDFShift response-time benchmarks, retry guarantees, or pricing details, so none are assumed here. Avoid repeatedly retrying an unchanged 401 or 403 request: inspect and correct the outgoing authentication configuration first.
FAQ
Does PDFShift still accept Basic Auth?
The current provider guidance says the API moved to the X-API-Key header on 2025-05-06. Use that header in new or updated requests.
Does a 401 prove the API key itself is invalid?
No. The available guidance says missing or incorrectly sent authentication may produce 401 or 403, without mapping every cause to a specific status.
What should I do if the usage endpoint works?
Retry conversion as a separate POST and inspect its response. Successful authentication at the diagnostic endpoint does not explain a later conversion failure by itself.
Can I use this fix for n8n?
Yes. In the documented HTTP Request node setup, send X-API-Key as a request header and set the authentication selector to None.
