Error Handling

Werk24 returns a TechreadMessage for each request. This message includes an exceptions array listing any issues detected while processing your files.

Key points

• Per-page granularity: Exceptions are tracked per page. If you upload a two-page document (e.g., a drawing on page 1 and an order form on page 2), you may receive valid results for page 1 and an exception for page 2.
• Success check: When using the Python models, prefer the is_successful property. If True, no blocking exceptions were found for the requested outputs.
• Levels: Only an exception with exception_level ERROR is blocking. A WARNING rides on a message whose results stand, such as a completed read that is knowingly incomplete (see Incomplete reads).

Quick check (Python)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

from werk24 import AskMetaData, get_test_drawing, read_drawing_sync

messages = read_drawing_sync(get_test_drawing(), [AskMetaData()])

for msg in messages:
    if msg.is_successful:
        print(f"✅ Page {msg.page_number}: requested output available.")
    else:
        print(f"❌ Page {msg.page_number} reported exceptions:")
        for ex in msg.exceptions:
            print(f"  - {ex.exception_level}: {ex.exception_type}")

Tip: Even when is_successful is False for one message, inspect the other messages, since you may still have usable outputs for unaffected pages.

Exception types

Version note: DRAWING_FILE_SIZE_TOO_LARGE is reported by the Python client when read_drawing cannot upload a drawing over 10 MiB. Version 2.7.0 is the exception: it raises a TypeError there instead, which is fixed in versions newer than 2.7.0. A callback request never receives this code: from versions newer than 2.7.0 the client raises CallbackDrawingTooLargeException before sending an oversized request; with version 2.7.0 or older, or without the client, the request is sent and refused without a request_id, so check the size yourself. See Drawing File Size Limit.

Version note: CONFIGURATION_INCORRECT requires client v2.3.0+. Older clients surface similar issues as DRAWING_CONTENT_NOT_UNDERSTOOD.

Version note: DRAWING_PAGE_COUNT_TOO_LARGE is only sent to clients reporting a version newer than 2.5.0 (the Python client added support in v2.6.0). Clients on v2.5.0 or older receive no redaction result and no error for over-limit documents. Upgrade to at least v2.6.0.

Incomplete reads

Some parts of a read are best-effort. When one of them could not finish, Werk24 still delivers everything it did read rather than failing the request, and says so on the final COMPLETED progress message with one exception: exception_level WARNING and exception_type READ_INCOMPLETE.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "message_type": "PROGRESS",
  "message_subtype": "COMPLETED",
  "exceptions": [
    {
      "exception_level": "WARNING",
      "exception_type": "READ_INCOMPLETE"
    }
  ]
}

The message is still successful: is_successful is True, and every result you already received stands. What the warning tells you is that some of those results may be less complete than the drawing allows.

Re-submitting the same drawing usually gives a complete read, because the causes are usually transient.

1
2
3
4

for msg in messages:
    for ex in msg.exceptions:
        if ex.exception_type == "READ_INCOMPLETE":
            print("⚠️ Read incomplete; results delivered so far stand.")

Version note: READ_INCOMPLETE warnings are only sent to clients reporting version 2.8.0 or newer. Older clients accept only the exception levels and types they know, so they receive the same COMPLETED message as before, without the warning.

What is billed

Werk24 bills per page. Whether a page is billed depends on whose side a problem was on:

• A page whose result was not delivered in full is not billed. When a read finishes with a READ_INCOMPLETE warning, only the pages that went out short are left off your bill; the other pages of the same request are billed. A page that ends in an ERROR while its siblings finish is not billed either.
• A read that fails on our side is not billed: an internal error, or a read that ran out of time.
• A read that fails on your side is billed: a file format we do not read, a resolution too low, too many pages, a paper size too large, an incorrect configuration, or a callback endpoint that refuses or cannot be reached. Sending the same drawing twice is two reads.
• A request refused before it is accepted is not billed: a 400, 401, 403 or 429 from the HTTP API, and a drawing over the size limit.

Troubleshooting checklist

1. Validate inputs: Confirm file format, page count and paper size. For raster inputs check resolution against the per-size targets rather than a single DPI number, because a figure that is fine on A4 is not on A1, and there is an upper limit as well. Check it yourself even for a scan saved as a PDF: nothing rejects those for resolution.
2. Reduce variability: Remove non-drawing pages (cover sheets, order forms) or upload them separately.
3. Tighten configuration: Ensure your request includes the correct hooks/asks and compatible options.
4. Retry selectively: If only some pages failed, re-submit just those pages after corrections.

Frequently asked

Why do I get an exception for one page but results for another? Exceptions are per page; a failure on page 2 doesn’t invalidate page 1.

Can I still use partial results? Yes. Iterate pages and consume outputs where is_successful is True. Checking that exceptions is empty is not enough: a completed read can carry a non-blocking WARNING.

My read completed with a READ_INCOMPLETE warning. Did it fail? No. The results you received are valid; some of them may be less complete than the drawing allows. See Incomplete reads.

How do I distinguish configuration errors from content errors? On client v2.3.0+, malformed requests return CONFIGURATION_INCORRECT. Otherwise, similar symptoms may appear as DRAWING_CONTENT_NOT_UNDERSTOOD.