Makralabs

Errors, events, and run states

Errors, events, and run states

Catch MakraError for any SDK exception. Catch narrower classes when the application has a specific recovery action.

Exception hierarchy

Exception Condition Useful fields
MakraAPIError Any HTTP API error status_code, body, method, path, code, request_id
MakraAuthenticationError Missing, invalid, revoked, or expired credential API error fields
MakraPermissionError Valid credential lacks permission API error fields
MakraNotFoundError Run or result absent or inaccessible API error fields
MakraInvalidRequestError Contract or URL admission rejection field, reason, index
MakraInsufficientCreditsError Balance cannot cover admission required_credits, available_credits
MakraRateLimitError Request or active-run limit retry_after, concurrency
MakraServerError API or upstream service failure API error fields
MakraConnectionError Transport could not reach API method, path
MakraTimeoutError Request or stream timeout Connection error fields
MakraStreamError Stream ended before terminal recovery run_id
MakraResultError Stored result redirect or download contract failed run_id, sanitized location
MakraRunFailedError Waited run ended outside completed run_id, state, run

Local argument validation raises ValueError, not MakraError.

from makra import Makra, MakraAPIError, MakraConnectionError

try:
    with Makra() as client:
        client.extract(
            ["https://shop.example/products/atlas-lamp"],
            {"price": "The current selling price"},
        )
except MakraAPIError as error:
    print(error.status_code, error.code, error.request_id)
    raise
except MakraConnectionError as error:
    print(error.method, error.path)
    raise

Run states

Non-terminal states are queued, running, and cancel_requested. Terminal states are completed, failed, cancelled, and budget_exhausted.

run_is_terminal(run) checks state membership. run_succeeded(run) requires completed and rejects an explicit domain success value of false.

Public event types

The event stream can emit run started, heartbeat, step started, step progress, step completed, partial result, diagnostic, run completed, run failed, run cancelled, and run budget exhausted events. Compare event.type with constants on EventTypes.

event.detail_type exposes finer internal progress names through StreamDetailTypes, including stage, activity, message, result, diagnostic, and title events. Treat unknown future detail types as observable events, not fatal parser errors.

Structured API error codes

Known gateway codes include insufficient credits, too many concurrent runs, idempotency key reuse, invalid workflow URL, invalid request contract, streaming unavailable, run not terminal, result not available, result temporarily unavailable, and not found.

Branch on exception class first. Use error.code when two conditions within one HTTP status need different recovery.

Return to What Makra is.