Error handling

When a request fails, the Nutrient DWS Data Extraction API returns an error response with an HTTP status code, a human-readable message, and structured details when available.

Error response format

The API uses this response shape for most errors:

interface ParseErrorResponse {
  /** HTTP status code (4xx or 5xx) */
  status: number;
  /** Unique request identifier for debugging / support */
  requestId: string;
  /** Human-readable error summary */
  errorMessage: string;
  /** Structured error details (present on validation and processing errors) */
  errorDetails?: {
    /** Error origin: "request", "processing", etc. */
    source: string;
    /** Stable machine-readable error code for client branching. */
    code?: string;
    /** List of invalid fields */
    failingPaths?: { path: string; details: string }[];
  };
}

The response can include these fields:

• requestId — Always present. Include this value when you contact Support. For support details, refer to the support guide.
• errorMessage — Short summary of the error.
• errorDetails.source — Error origin, such as request for validation errors, processing, or maestro for backend failures.
• errorDetails.code — Machine-readable error code for client branching, such as invalid_request or maestro_error.
• errorDetails.failingPaths — Invalid fields with JSON paths and descriptions.

HTTP status codes

Use the HTTP status code to decide how your client should handle an error.

Error examples

The following examples show the response format for common error categories.

Validation error (400)

The API returns this error when the request has invalid parameters or an unsupported file format:

{
  "status": 400,
  "requestId": "req_err_001",
  "errorMessage": "The request is malformed",
  "errorDetails": {
    "source": "request",
    "code": "invalid_request",
    "failingPaths": [
      {
        "path": "$.file",
        "details": "unsupported file format: video/mp4"
      },
      {
        "path": "$.mode",
        "details": "invalid mode: 'turbo'. Expected: text, structure, understand, agentic"
      }
    ]
  }
}

Insufficient credits (402)

The API returns this error when the account doesn’t have enough credits to process the request:

{
  "status": 402,
  "requestId": "req_err_002",
  "errorMessage": "Insufficient credits. This request requires 2 credits, 0 remaining."
}

Processing error (500)

The API returns this error when the backend encounters an internal error during extraction:

{
  "status": 500,
  "requestId": "req_err_003",
  "errorMessage": "Processing failed. Please retry or contact support with the requestId.",
  "errorDetails": {
    "source": "maestro",
    "code": "maestro_error"
  }
}

Extract endpoint errors

The extract endpoint uses the same error shape as parse, plus cases specific to schema-driven extraction. For endpoint details, refer to the extract endpoint guide.

Schema validation errors (400)

The API rejects a request when the schema is missing or uses an unsupported structure. The failingPaths entry points to $.schema:

{
  "status": 400,
  "requestId": "req_err_002",
  "errorMessage": "The request is malformed",
  "errorDetails": {
    "source": "request",
    "failingPaths": [
      {
        "path": "$.schema",
        "details": "root schema type must be \"object\", got \"array\""
      }
    ]
  }
}

Common causes include a missing schema, a root type other than object, or unsupported keywords such as $ref, composition keywords, and validation ranges. For the supported subset and limits, refer to the define a schema guide.

Remote URL rejected (422)

The API returns this error when it can’t download a url input or rejects the URL:

{
  "status": 422,
  "requestId": "req_err_url",
  "errorMessage": "The request is malformed",
  "errorDetails": {
    "source": "request",
    "failingPaths": [{ "path": "$.url", "details": "URL is not allowed" }]
  }
}

Insufficient credits (402)

The extract endpoint returns a different body shape for insufficient credits than the parse endpoint:

{
  "error": "insufficient_credits",
  "message": "Your organization has insufficient credits for this operation.",
  "credits_available": "0"
}

Branch on the HTTP status code, 402, rather than the body shape so your error handling works across both endpoints.

Handle errors in code

The following examples show how to read error fields from a response.

import requests

response = requests.post(
    "https://api.nutrient.io/extraction/parse",
    headers={"Authorization": "Bearer your_api_key_goes_here"},
    files={"file": open("document.pdf", "rb")},
)

result = response.json()

if result.get("status") != 200:
    print(f"Error {result['status']}: {result['errorMessage']}")
    print(f"Request ID: {result['requestId']}")
    if "errorDetails" in result:
        if result["errorDetails"].get("code"):
            print(f"Error code: {result['errorDetails']['code']}")
        for path in result["errorDetails"].get("failingPaths", []):
            print(f"  {path['path']}: {path['details']}")
else:
    print(f"Extracted {len(result['output'].get('elements', []))} elements")

const response = await fetch("https://api.nutrient.io/extraction/parse", {
  method: "POST",
  headers: { Authorization: "Bearer your_api_key_goes_here" },
  body: form,
});

const result = await response.json();

if (result.status !== 200) {
  console.error(`Error ${result.status}: ${result.errorMessage}`);
  console.error(`Request ID: ${result.requestId}`);
  if (result.errorDetails?.code) {
    console.error(`Error code: ${result.errorDetails.code}`);
  }
  if (result.errorDetails?.failingPaths) {
    result.errorDetails.failingPaths.forEach((p) => {
      console.error(`  ${p.path}: ${p.details}`);
    });
  }
} else {
  console.log(`Extracted ${result.output.elements?.length ?? 0} elements`);
}

Troubleshooting

Diagnose common request failures by status code and symptom.

Request returns 401

Verify that the Authorization header uses the format Bearer pdf_live_....

Request returns 413

The file exceeds the maximum size of 150 MB. Reduce the file size or split multipage documents before uploading. For file requirements, refer to the supported file types guide.

Request returns 429

You exceeded the rate limit. Wait and retry with exponential backoff. Check your plan limits in the Data Extraction API dashboard(opens in a new tab).

Request returns 500 or 503

These are server-side errors. Retry the request after a short delay. If the error persists, contact Support and include the requestId from the response. For support details, refer to the support guide.