Processing Priority

Introduction

When submitting drawing requests to the Werk24 API, each request is assigned a processing priority that determines its position in the processing queue. Understanding priorities helps you optimize your workflow, especially when handling both time-sensitive and batch processing tasks.

What Is Processing Priority?

Processing priority determines the order in which drawing requests are processed by the Werk24 API. Higher priority requests are processed before lower priority ones, allowing time-sensitive work to complete faster while batch jobs can be queued at lower priority.

The Werk24 API supports three priority levels:

Priority	Level	Description	Typical Use Case
PRIO1	Highest	Fastest processing, processed first	Real-time user interactions, urgent requests
PRIO2	Medium	Standard processing speed	Normal workflow, moderate urgency
PRIO3	Lowest	Batch processing, processed last	Background jobs, overnight processing

Account Tier and Priority

Your account tier determines the maximum priority level available to you:

PRIO1 accounts: Can use PRIO1, PRIO2, or PRIO3
PRIO2 accounts: Can use PRIO2 or PRIO3
PRIO3 accounts: Can only use PRIO3

By default, requests use your account's maximum priority. The priority override feature allows you to voluntarily use a lower priority than your account allows.

Why Use Priority Override?

Priority override is useful when you want to:

Batch Processing: Queue large volumes of drawings at lower priority without impacting your real-time requests
Cost Optimization: Some pricing tiers may offer benefits for lower-priority processing
Resource Management: Separate urgent work from background tasks
Fair Queuing: Allow other users' urgent requests to process while your batch jobs wait

Using Priority Override

Basic Usage with read_drawing()

import asyncio
from werk24 import Werk24Client, AskMetaData

async def process_drawing_with_priority():
    async with Werk24Client() as client:
        with open("drawing.pdf", "rb") as f:
            # Process with default priority (account tier)
            async for message in client.read_drawing(f, [AskMetaData()]):
                print(message)

            # Process with explicit lower priority
            f.seek(0)  # Reset file position
            async for message in client.read_drawing(
                f, 
                [AskMetaData()], 
                priority="PRIO3"  # Use lowest priority for batch
            ):
                print(message)

asyncio.run(process_drawing_with_priority())

Using with Hooks

import asyncio
from werk24 import Werk24Client, AskMetaData, Hook, TechreadMessage

def handle_result(message: TechreadMessage):
    if message.is_successful:
        print(f"Processed: {message.payload_dict}")

async def batch_process():
    hooks = [Hook(ask=AskMetaData(), function=handle_result)]

    async with Werk24Client() as client:
        with open("drawing.pdf", "rb") as f:
            # Use PRIO3 for batch processing
            await client.read_drawing_with_hooks(
                f, 
                hooks, 
                priority="PRIO3"
            )

asyncio.run(batch_process())

Using with Callbacks

import asyncio
from werk24 import Werk24Client, AskMetaData

async def submit_batch_job():
    async with Werk24Client() as client:
        with open("drawing.pdf", "rb") as f:
            request_id = await client.read_drawing_with_callback(
                f,
                asks=[AskMetaData()],
                callback_url="https://your-server.com/webhook",
                priority="PRIO3"  # Lower priority for batch
            )
            print(f"Submitted batch job: {request_id}")

asyncio.run(submit_batch_job())

Using CURL with Callbacks

You can also submit callback requests directly via the REST API with a priority override:

curl -X POST "https://api.w24.co/techread/read-with-callback" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "drawing=@drawing.pdf" \
  -F "asks=[{\"askType\": \"META_DATA\"}]" \
  -F "callback_url=https://your-server.com/webhook" \
  -F "max_pages=5" \
  -F "priority=PRIO3"

The response contains the request ID for tracking:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Your callback endpoint will receive the results once processing completes.

Priority Values Are Case-Insensitive

The client accepts priority values in any case:

# All of these are equivalent
priority="PRIO1"
priority="prio1"
priority="Prio1"

The client normalizes the value to uppercase before sending to the server.

Error Handling

PriorityTooHighError

This exception is raised when you request a priority higher than your account tier allows.

import asyncio
from werk24 import Werk24Client, AskMetaData, PriorityTooHighError

async def handle_priority_error():
    async with Werk24Client() as client:
        try:
            with open("drawing.pdf", "rb") as f:
                async for message in client.read_drawing(
                    f, 
                    [AskMetaData()], 
                    priority="PRIO1"  # May fail if account is PRIO2 or PRIO3
                ):
                    print(message)
        except PriorityTooHighError as e:
            print(f"Priority too high!")
            print(f"Your account tier: {e.account_tier}")
            print(f"Requested priority: {e.requested_priority}")
            print(f"Try using priority='{e.account_tier}' or lower")

asyncio.run(handle_priority_error())

Exception attributes:

account_tier: Your account's maximum allowed priority (e.g., "PRIO2")
requested_priority: The priority you attempted to use (e.g., "PRIO1")

InvalidPriorityError

This exception is raised when you provide an invalid priority value.

import asyncio
from werk24 import Werk24Client, AskMetaData, InvalidPriorityError

async def handle_invalid_priority():
    async with Werk24Client() as client:
        try:
            with open("drawing.pdf", "rb") as f:
                async for message in client.read_drawing(
                    f, 
                    [AskMetaData()], 
                    priority="INVALID"  # Not a valid priority
                ):
                    print(message)
        except InvalidPriorityError as e:
            print(f"Invalid priority value: {e.invalid_value}")
            print("Valid values are: PRIO1, PRIO2, PRIO3")

asyncio.run(handle_invalid_priority())

Exception attributes:

invalid_value: The invalid priority string you provided

Best Practices

1. Use Default Priority for Interactive Requests

For user-facing applications where response time matters, don't specify a priority—let it default to your account's maximum:

# Good: Uses account's default priority
async for message in client.read_drawing(f, asks):
    process(message)

2. Use PRIO3 for Batch Processing

When processing large volumes of drawings overnight or in the background:

# Good: Explicitly use lowest priority for batch
async for message in client.read_drawing(f, asks, priority="PRIO3"):
    process(message)

3. Handle Priority Errors Gracefully

Always catch priority-related exceptions in production code:

from werk24 import PriorityTooHighError, InvalidPriorityError

try:
    async for message in client.read_drawing(f, asks, priority=user_priority):
        process(message)
except PriorityTooHighError as e:
    # Fall back to account tier
    async for message in client.read_drawing(f, asks, priority=e.account_tier):
        process(message)
except InvalidPriorityError as e:
    logger.error(f"Invalid priority '{e.invalid_value}' - using default")
    async for message in client.read_drawing(f, asks):
        process(message)

4. Separate Queues by Priority

For applications with mixed workloads, consider separating requests by priority:

async def process_urgent(drawing_path: str):
    """Process urgent requests at default (highest) priority."""
    async with Werk24Client() as client:
        with open(drawing_path, "rb") as f:
            async for message in client.read_drawing(f, asks):
                yield message

async def process_batch(drawing_paths: list[str]):
    """Process batch requests at lowest priority."""
    async with Werk24Client() as client:
        for path in drawing_paths:
            with open(path, "rb") as f:
                async for message in client.read_drawing(f, asks, priority="PRIO3"):
                    yield message