---
title: "Error handling"
canonical_url: "https://www.nutrient.io/guides/dws-data-extraction/errors/"
md_url: "https://www.nutrient.io/guides/dws-data-extraction/errors.md"
last_updated: "2026-06-11T00:00:00.000Z"
description: "HTTP status codes, error response format, and troubleshooting for the Nutrient Data Extraction API."
---

# 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:

```typescript

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](https://www.nutrient.io/guides/dws-data-extraction/support.md) 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.

| Status | Meaning               | Description                                                                        |
| ------ | --------------------- | ---------------------------------------------------------------------------------- |
| 400    | Bad request           | Missing file or URL, invalid parameters, unsupported file format, or schema error. |
| 401    | Unauthorized          | Missing, invalid, or expired API token.                                            |
| 402    | Payment required      | Insufficient credits for the requested operation.                                  |
| 408    | Request timeout       | Request timed out for the extract endpoint.                                        |
| 413    | Payload too large     | File exceeds the maximum supported size.                                           |
| 422    | Unprocessable entity  | Remote URL couldn’t be downloaded or was rejected by the extract endpoint.         |
| 429    | Too many requests     | Rate limit exceeded for your subscription.                                         |
| 500    | Internal server error | Backend processing failure. Retry or contact Support.                              |
| 503    | Service unavailable   | Processing backend is temporarily unavailable. Retry later.                        |

## 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:

```json

{
  "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:

```json

{
  "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:

```json

{
  "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](https://www.nutrient.io/guides/dws-data-extraction/extract.md) 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`:

```json

{
  "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](https://www.nutrient.io/guides/dws-data-extraction/extract/define-a-schema.md) guide.

### Remote URL rejected (422)

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

```json

{
  "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:

```json

{
  "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.

### Python

```python

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")

```

### JavaScript

```javascript

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](https://www.nutrient.io/guides/dws-data-extraction/file-types.md) 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](https://dashboard.nutrient.io/).

### 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](https://www.nutrient.io/guides/dws-data-extraction/support.md) guide.
---

## Related pages

- [API overview](/guides/dws-data-extraction/api-overview.md)
- [Supported file types](/guides/dws-data-extraction/file-types.md)
- [Get started](/guides/dws-data-extraction/getting-started.md)
- [DWS Data Extraction API](/guides/dws-data-extraction.md)
- [Privacy](/guides/dws-data-extraction/privacy.md)
- [Support](/guides/dws-data-extraction/support.md)
- [Security](/guides/dws-data-extraction/security.md)
- [Supported languages](/guides/dws-data-extraction/supported-languages.md)