Errors

Sometimes PSPDFKit API encounters an error with the provided inputs: the instructions JSON object, and the parts the user uploaded. When this occurs, an error JSON object is returned. This object will have the following shape:

type FailingPath = {
  path: string;
  details: string;
};

type Error = {
  details: string;
  status: number;
  requestId: string;
  failingPaths: FailingPath[];
};

Let’s go through the most important properties:

• details — A general description of what went wrong.
• status — This should match the HTTP status of the response. Added in case the request status gets modified by any proxy it might go through.
• requestId — An internal ID we attach to each request. When you contact support, we can use this to associate your support request with our internal logging.
• failingPaths — This will point to the specific parts of the request that actually caused the failure. Using this, you can easily figure out what to adjust to make your request work. In case of multiple errors in your request, this will contain all that could be found until processing had to be stopped.
  • path — This is in the JSONPath format and will point to the exact key in the instructions object that caused the request to fail.
  • details — A detailed error message for the failing path.

Examples

The following examples are meant to give an idea of how common errors returned by the API might look.

Wrong Page Index

Given the instructions for a PDF with only two pages:

{
  "parts": [{ "file": "pdf-1", "pages": { "start": 2, "end": 2 } }]
}

You’d get the following error:

{
  "details": "There was an error with one or more parts of the instructions.",
  "status": 400,
  "requestId": "random-id",
  "failingPaths": [
    {
      "path": "$.instructions.parts[0].pages.end",
      "details": "index 2 is out of range in document with 2 pages",
    },
    {
      "path": "$.instructions.parts[0].pages.start",
      "details": "index 2 is out of range in document with 2 pages"
    }
  ]
}

The failingPaths array tells you exactly which part of your request caused the failure. In this case, both the start page and end page are out of range.

Illegal File Format

Given the instructions for multiple files, including one text file:

{
  "parts": [
    { "file": "pdf-1" },
    { "file": "pdf-2" },
    { "file": "pdf-3" },
    { "file": "text-4" }
  ]
}

You’d get the following error:

{
  "details": "There was an error with one or more parts of the instructions.",
  "status": 400,
  "requestId": "random-id",
  "failingPaths": [
    {
      "path": "$.text-4",
      "details": "is of the unsupported mimetype text/plain"
    }
  ]
}

Here, the failingPaths array doesn’t point to a location inside the instructions object. Instead, it points to $.text-4. This lets you know that the uploaded file with the name text-4 is what caused the error to be returned.

For further reading, refer to the API Reference — specifically the section at the bottom regarding status codes.