SDK errors, retries & idempotency

from modulex import ModulexError

try:
    await client.workflows.get("wf-does-not-exist")
except ModulexError as e:
    print(e.status_code)   # int | None  (None for stream/timeout)
    print(e.message)       # human-readable summary
    print(e.body)          # parsed envelope (dict) or {"detail": text}
    print(e.response)      # the raw httpx.Response (or None)

import { ModulexError } from 'modulex-js';

try {
  await client.workflows.get('wf-does-not-exist');
} catch (e) {
  if (e instanceof ModulexError) {
    console.log(e.status);   // number | undefined
    console.log(e.message);  // human-readable summary
    console.log(e.body);     // parsed envelope or { detail: <statusText> }
    console.log(e.headers);  // raw Headers | undefined
    console.log(e.code, e.layer, e.reason); // structured fields, if present
  }
}

from modulex import (
    Modulex, ModulexError, NotFoundError, RateLimitError,
    BillingError, CreditExhaustedError, ValidationError,
)

async with Modulex(api_key="mx_live_...", organization_id="org-uuid") as client:
    try:
        await client.executions.run(workflow_id="wf-uuid", input={"messages": []})
    except CreditExhaustedError as e:          # 402, layer="credit"
        print(f"Out of credits: {e.current}/{e.limit} (code={e.code})")
    except BillingError as e:                   # any quota/credit/wallet/rate denial
        print(f"Denied [{e.layer}/{e.code}]: {e.reason}")
    except RateLimitError as e:                 # 429 (header path)
        print(f"Backoff {e.retry_after}s (limit={e.limit}, remaining={e.remaining})")
    except NotFoundError:
        print("Not found (or not owned by your org — same 404)")
    except ValidationError as e:
        print(f"422: {e.message}")
    except ModulexError as e:                   # catch-all, incl. base for unmapped >= 400
        print(f"API error ({e.status_code}): {e.message}")

// JavaScript has NO billing subclasses. A 402, or a rate-layer denial envelope,
// falls through to the base ModulexError — but .code, .layer, and .reason are
// still populated from the envelope, so you branch on those fields instead.
import { Modulex, RateLimitError, NotFoundError, ValidationError, ModulexError } from 'modulex-js';

try {
  await client.workflows.run({ workflowId: 'wf-uuid', input: { messages: [] } });
} catch (e) {
  if (e instanceof RateLimitError) {
    console.log(`429: retry after ${e.retryAfter}s`);
  } else if (e instanceof ModulexError && e.status === 402) {
    console.log(`Payment required [${e.layer}/${e.code}]: ${e.reason}`);
  } else if (e instanceof NotFoundError) {
    console.log('Not found (or not owned by your org)');
  } else if (e instanceof ValidationError) {
    console.log('422:', e.body);
  } else if (e instanceof ModulexError) {
    console.log(e.status, e.code, e.layer, e.reason);
  }
}

from modulex import Modulex

client = Modulex(
    api_key="mx_live_...",
    organization_id="org-uuid",
    max_retries=5,   # default 3; constructor-only (no env fallback)
    timeout=30.0,    # seconds; default 30.0
)

import { Modulex } from 'modulex-js';

const client = new Modulex({
  apiKey: 'mx_live_...',
  organizationId: 'org-uuid',
  maxRetries: 5,   // default 3
  timeout: 30_000, // milliseconds; default 30_000
});

# With raw HTTP you implement retries yourself. Retry only 429/500/502/503,
# and honor the Retry-After header on a 429.
curl -sS -X POST https://api.modulex.dev/workflows/run \
  -H "Authorization: Bearer mx_live_..." \
  -H "X-Organization-ID: org-uuid" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "wf-uuid", "input": {"messages": []}, "stream": false}'