Error Handling

Understanding and handling errors in DocDigitizer APIs.

Error Response Format

All errors follow this structure:

{
  "StateText": "ERROR",
  "TraceId": "XYZ7890",
  "Timers": {
    "DocIngester_Total": 45.23
  },
  "Messages": [
    "Human-readable error message"
  ]
}

Response Fields

HTTP Status Codes

400 Bad Request

Invalid request parameters or file format.

Common causes:

• File is not a valid PDF
• Missing required parameters (id, contextID)
• Invalid UUID format

Example:

{
  "StateText": "ERROR",
  "TraceId": "BAD1234",
  "Messages": ["File must be a PDF document"]
}

Resolution:

• Verify the file is a valid PDF
• Check all required parameters are provided
• Ensure UUIDs are properly formatted

401 Unauthorized

Authentication failed.

Common causes:

• Missing X-API-Key header
• Invalid or revoked API key
• Expired API key

Example:

{
  "StateText": "ERROR",
  "TraceId": "UNA1234",
  "Messages": ["Invalid or missing API key"]
}

Resolution:

• Verify the X-API-Key header is included
• Check the API key is correct and active
• Generate a new key if needed

403 Forbidden

Authorization failed - key is valid but lacks permission.

Common causes:

• Subscription doesn't include this feature
• API key doesn't have required scope
• Account suspended

Resolution:

• Check your subscription plan
• Verify the API key's permissions
• Contact support if your account may be suspended

500 Internal Server Error

Server-side processing error.

Common causes:

• Document processing failed
• Downstream service error
• Temporary system issue

Example:

{
  "StateText": "ERROR",
  "TraceId": "ERR9876",
  "Messages": [
    "DocWorker returned error: 500",
    "Processing failed. Check server logs for details."
  ]
}

Resolution:

• Retry the request after a short delay
• If persistent, contact support with the TraceId

503 Service Unavailable

Service temporarily unavailable.

Common causes:

• System maintenance
• Downstream service unreachable
• Resource exhaustion

Example:

{
  "StateText": "ERROR",
  "TraceId": "SVC1234",
  "Messages": ["Cannot connect to DocWorker: Connection refused"]
}

Resolution:

• Wait and retry with exponential backoff
• Check system status if available
• Contact support if issue persists

504 Gateway Timeout

Request took too long to process.

Common causes:

• Very large document
• Complex document structure
• System under heavy load

Example:

{
  "StateText": "ERROR",
  "TraceId": "TMO1234",
  "Messages": ["DocWorker request timed out"]
}

Resolution:

• For large documents, consider splitting
• Retry during off-peak hours
• Contact support for large document processing

Error Handling Best Practices

1. Always Check StateText

result = response.json()

if result["StateText"] == "ERROR":
    handle_error(result)
else:
    process_success(result)

2. Log the TraceId

Always log the TraceId for debugging:

if result["StateText"] == "ERROR":
    logger.error(f"API Error - TraceId: {result['TraceId']}, Messages: {result['Messages']}")

3. Implement Retry Logic

For transient errors (5xx), implement retry with backoff:

import time
import random

def process_with_retry(file_path, max_retries=3):
    for attempt in range(max_retries):
        result = call_api(file_path)

        if result["StateText"] != "ERROR":
            return result

        # Check if error is retryable
        if response.status_code < 500:
            raise NonRetryableError(result["Messages"])

        # Exponential backoff with jitter
        delay = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(delay)

    raise MaxRetriesExceeded()

4. Handle Specific Error Types

def handle_error(result, status_code):
    trace_id = result.get("TraceId", "unknown")
    messages = result.get("Messages", ["Unknown error"])

    if status_code == 400:
        # Client error - fix the request
        raise ValidationError(messages, trace_id)

    elif status_code == 401:
        # Auth error - check API key
        raise AuthenticationError(messages, trace_id)

    elif status_code == 403:
        # Permission error - check subscription
        raise PermissionError(messages, trace_id)

    elif status_code in [500, 502, 503, 504]:
        # Server error - retry
        raise RetryableError(messages, trace_id)

    else:
        raise UnknownError(messages, trace_id)

Common Errors and Solutions

Getting Help

When contacting support, always include:

1. TraceId from the error response
2. Timestamp of when the error occurred
3. Request details (endpoint, parameters)
4. File information (size, number of pages if known)

Contact: [email protected]