Error Codes

When something goes wrong, PDFShot returns a JSON error response with details about what happened.

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "HTML content is required when url is not provided"
  }
}

HTTP Status Codes

Error Code Reference

Authentication Errors (401, 403)

Fix: Check that your API key is correct and active in your Dashboard.

Billing Errors (402)

Fix: Add a payment method in your Billing Settings to continue using the API.

Validation Errors (400)

Common validation issues:

• Missing both html and url
• Providing both html and url (only one allowed)
• HTML exceeds 10MB limit
• Invalid option values

Timeout Errors (504)

Fix: Simplify your HTML, reduce external resource loading, or break into smaller documents.

Server Errors (500)

Fix: Try again. If the problem persists, contact support.

Troubleshooting

"Missing or invalid Authorization header"

Make sure you're including the header correctly:

# Correct
-H "Authorization: Bearer pds_your_key_here"

# Wrong - missing "Bearer"
-H "Authorization: pds_your_key_here"

# Wrong - missing space after "Bearer"
-H "Authorization: Bearerpds_your_key_here"

"Invalid API key"

1. Check that you copied the full key (should start with pds_)
2. Verify the key is active in your Dashboard
3. Try creating a new key

"Free tier exceeded"

You've used your 5 free minutes this month. Options:

1. Wait until next month for the free tier to reset
2. Add a payment method to continue using the API

"Conversion failed"

Common causes:

• JavaScript errors preventing page render
• Missing fonts or images
• Invalid HTML structure

Try:

1. Test your HTML in a browser first
2. Use fully qualified URLs for external resources
3. Include inline styles instead of external stylesheets

"Timeout"

The 2-minute limit was exceeded. Common causes:

• Slow external resources (fonts, images, scripts)
• Extremely large documents
• Heavy JavaScript processing

Try:

1. Inline critical CSS and fonts
2. Compress images
3. Remove unnecessary JavaScript
4. Split large documents into smaller requests

Rate Limits

If you exceed rate limits, you'll receive a 429 Too Many Requests response.

Getting Help

If you're stuck:

1. Check the error code and message
2. Review this troubleshooting guide
3. Test your HTML in a browser
4. Contact support at support@pdfshot.com