---
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-05-26T22:37:31.557Z"
description: "HTTP status codes, error response format, and troubleshooting for the Nutrient Data Extraction API."
---

# Error handling

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

## Error response format

```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 }[];
  };
}

```

- `requestId` — Always present. Include this when [contacting Support](https://www.nutrient.io/guides/dws-data-extraction/support.md).

- `errorMessage` — A short summary of the error.

- `errorDetails.source` — Where the error occurred: `request` for validation errors, `processing`, or `maestro` for backend failures.

- `errorDetails.code` — Machine-readable error code for client branching (e.g. `invalid_request`, `maestro_error`).

- `errorDetails.failingPaths` — Lists the invalid fields with JSON paths and descriptions.

## HTTP status codes

| Status | Meaning               | Description                                                      |
| ------ | --------------------- | ---------------------------------------------------------------- |
| 400    | Bad request           | Missing file or URL, invalid parameters, unsupported file format |
| 401    | Unauthorized          | Missing, invalid, or expired API token                           |
| 402    | Payment required      | Insufficient credits for the requested operation                 |
| 413    | Payload too large     | File exceeds the maximum allowed size                            |
| 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 down. Retry later.             |

## Error examples

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

### Validation error (400)

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

Returned when the account does not 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)

Returned 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"
  }
}

```

## Handling errors in code

### 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 the `Authorization` header uses the format `Bearer pdf_live_...`.

### Request returns 413

The file exceeds the [maximum size of 150 MB](https://www.nutrient.io/guides/dws-data-extraction/file-types.md). Reduce the file size or split multipage documents before uploading.

### Request returns 429

You have exceeded the rate limit. Wait and retry with exponential backoff. Check your plan limits in the [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](https://www.nutrient.io/guides/dws-data-extraction/support.md) and include the `requestId` from the response.
---

## 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)
- [Support](/guides/dws-data-extraction/support.md)
- [Security](/guides/dws-data-extraction/security.md)
- [Privacy](/guides/dws-data-extraction/privacy.md)
- [Supported languages](/guides/dws-data-extraction/supported-languages.md)