pdfRest Improves Developer Experience with Smarter API Validation

pdfRest has rolled out a series of API improvements focused on making the developer experience smoother and more predictable. The updates center on two key areas: richer error messages that help developers fix problems faster, and more flexible parameter handling that eliminates unnecessary stumbling blocks during integration.

These enhancements turn unexpected roadblocks into clear directions, accelerating development velocity for engineers building complex document workflows.

Error Messages That Teach, Not Just Reject

Previously, when a pdfRest API request included an invalid parameter value, the error response identified the problem but left the developer to figure out the solution independently. For example, sending an invalid page_size value to the /pdf endpoint would return:

JSON

{
"error": "large is not within the acceptable range for page_size"
}
This tells the developer something went wrong, but not how to fix it. With the latest update, error responses now include a detailed errorDetail object that specifies exactly what was wrong, where it was wrong, and what the accepted values are:

JSON

{
"error": "large is not within the acceptable range for page_size",
"errorDetail": {
"issues": [
{
"path": "fields.page_size",
"message": "Invalid option: expected one of "letter"|"legal"|"ledger"|"A3"|"A4"|"A5"",
"allowedValues": [
"letter", "legal", "ledger", "A3", "A4", "A5"
],
"value": "large"
}
]
}

The new response tells the developer the exact field path, the value they submitted, the full list of accepted values, and a human-readable message explaining the constraint. This eliminates the round-trip to documentation for common validation errors and significantly reduces debugging time during integration.

This level of detail is designed to be highly readable by human developers testing and building against the API, but the structured, predictable format also makes it straightforward for automated systems and AI coding tools to parse responses and programmatically correct their requests.

Flexible Parameter Acceptance

The second improvement addresses a common source of friction. The underlying tools within pdfRest have historically varied in which syntax they accept for binary parameters; some routes expected true or false, others required on or off, and still others used 1 or 0. Without an externally obvious logic to the inconsistency, developers working across multiple endpoints would occasionally encounter unnecessary validation errors.
For example, the tagged_pdf option in the /pdf endpoint documents on or off as its accepted values. Sending true would previously return an error:

JSON

{
"error": "true is not within the acceptable range for tagged_pdf"
}

With the latest update, the API now accepts all common boolean representations like true/false, on/off, and 1/0 across endpoints and maps them to the correct internal value automatically. Developers no longer need to memorize or look up the exact parameter syntax for each route. The API meets them where they are.

A Smoother Path from First Call to Production

Together, these improvements reduce friction at two critical points in the developer journey: initial integration, where unclear errors slow progress, and multi-endpoint adoption, where inconsistent parameter handling creates unnecessary stumbling blocks. The result is an API that is faster to learn, easier to debug, and more forgiving during development, all while maintaining the precision that production workflows require. For full technical details, visit the pdfRest release notes.

Getting Started

Developers can get started for free and begin testing and generating code immediately by accessing the API Lab, which allows users to upload files, choose parameters, and execute API calls directly from their browser.