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

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.
• 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

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:

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

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

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

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

Request returns 429

You have exceeded the rate limit. Wait and retry with exponential backoff. Check your plan limits in the 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.