Error Handling¶

The MicroDC client provides a hierarchy of exception classes for handling different error scenarios.

Exception Hierarchy¶

MicroDCError (base)
├── AuthenticationError     # Invalid or expired API key
├── ValidationError         # Invalid job configuration
├── APIError                # Server-side errors
├── TimeoutError            # Operation timeout
├── JobNotFoundError        # Job ID doesn't exist
├── RateLimitError          # Too many requests
└── InsufficientCreditsError  # Not enough credits

Basic Error Handling¶

from microdc import (
    Client, LLMComplete,
    AuthenticationError,
    ValidationError,
    InsufficientCreditsError,
    APIError,
    TimeoutError
)

try:
    client = Client(api_key="mDC_...")

    job = LLMComplete(model="llama3.3")
    job.set_prompt("Hello!")

    job_id = client.send_job(job)
    result = client.wait_for_job(job_id, timeout=60)

    print(result.result)

except AuthenticationError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Invalid job config: {e}")
except InsufficientCreditsError as e:
    print(f"Need {e.required} credits, have {e.available}")
except TimeoutError:
    print("Job took too long")
except APIError as e:
    print(f"API error (status {e.status_code}): {e}")
finally:
    client.close()

Exception Details¶

AuthenticationError¶

Raised when the API key is invalid or expired.

try:
    client = Client(api_key="invalid_key")
    client.send_job(job)
except AuthenticationError:
    print("Check your API key")

ValidationError¶

Raised when job configuration is invalid (before sending to the API).

try:
    job = LLMComplete(model="")  # Empty model
    job.set_prompt("Hello")
    client.send_job(job)
except ValidationError as e:
    print(f"Fix your job config: {e}")

APIError¶

Raised for server-side errors. Includes the HTTP status code.

try:
    client.send_job(job)
except APIError as e:
    print(f"Status code: {e.status_code}")
    print(f"Message: {e}")

RateLimitError¶

Raised when you exceed the API rate limit. Includes a retry_after hint.

import time

try:
    client.send_job(job)
except RateLimitError as e:
    if e.retry_after:
        print(f"Retry after {e.retry_after} seconds")
        time.sleep(e.retry_after)

InsufficientCreditsError¶

Raised when your account doesn't have enough credits.

try:
    client.send_job(job)
except InsufficientCreditsError as e:
    print(f"Required: {e.required}, Available: {e.available}")

JobNotFoundError¶

Raised when a job ID doesn't exist.

try:
    details = client.get_job_details("nonexistent_job_id")
except JobNotFoundError:
    print("Job not found")

Checking Job Status¶

Jobs can fail even after successful submission. Always check the result:

details = client.get_job_details(job_id)

if details.is_successful():
    print(details.result)
elif details.is_failed():
    print(f"Job failed: {details.error_message}")

JobDetails Status Methods¶

Method	Returns `True` when
`is_completed()`	Status is `completed`, `failed`, or `cancelled`
`is_successful()`	Status is `completed`
`is_failed()`	Status is `failed`

Automatic Retry Logic¶

The client automatically retries transient errors:

Retry attempts: 3
Base delay: 1 second (exponential backoff)
Retryable status codes: 408, 429, 500, 502, 503, 504

Non-retryable errors (400, 401, 403, 404) raise immediately.

Catching All MicroDC Errors¶

Use the base class to catch any MicroDC-specific error:

from microdc import MicroDCError

try:
    # Any MicroDC operation
    client.send_job(job)
except MicroDCError as e:
    print(f"MicroDC error: {e}")