Errors & status codes

{
  "detail": "X-Organization-ID header is required"
}

{
  "detail": {
    "code": "rate_limited",
    "layer": "rate",
    "key": "api",
    "current": 300,
    "limit": 300,
    "reason": "rate_limit_exceeded"
  }
}

{
  "detail": [
    {
      "loc": ["query", "q"],
      "msg": "String should have at least 2 characters",
      "type": "string_too_short"
    }
  ]
}

{
  "code": "credit_plan_exhausted",
  "layer": "credit",
  "key": "sync_exec",
  "current": null,
  "limit": 5000.0,
  "reason": "credit_plan_exhausted"
}

# A 402 DenialEnvelope from the run surface looks like this on the wire.
# Branch on the top-level `layer` / `code` (no `detail` wrapper).
curl -i -X POST https://api.modulex.dev/workflows/run \
  -H "Authorization: Bearer mx_live_8Kd2pQ7nR4xWvL0eYbT1" \
  -H "X-Organization-ID: org_9a2f7c41" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "wf_3f8a21c0", "input": {"topic": "quarterly report"}}'

# HTTP/1.1 402 Payment Required
# {"code":"credit_plan_exhausted","layer":"credit","key":"sync_exec",
#  "current":null,"limit":5000.0,"reason":"credit_plan_exhausted"}

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

async with Modulex(
    api_key="mx_live_8Kd2pQ7nR4xWvL0eYbT1",
    organization_id="org_9a2f7c41",
) as client:
    try:
        run = await client.executions.run(
            workflow_id="wf_3f8a21c0",
            input={"topic": "quarterly report"},
        )
    except CreditExhaustedError as err:
        # 402, layer="credit": plan allowance is used up.
        print(err.code, err.layer, err.limit)
    except WalletError as err:
        # 402, layer="wallet": overage off or balance insufficient.
        print(err.code, err.reason)
    except QuotaExceededError as err:
        # 403, layer="quota": a countable entitlement is at its limit.
        print(err.code, err.key, err.current, err.limit)
    except (RateLimitError, BillingError) as err:
        # 429 can raise either class — catch both. Back off on Retry-After.
        retry_after = getattr(err, "retry_after", None)
        print("rate limited; retry after", retry_after)
    except ValidationError as err:
        # 422: err.body["detail"] is the loc/msg/type array.
        print(err.body)
    except ModulexError as err:
        # Base catch-all for 402 falling through, 410, 409, 5xx, etc.
        print(err.status_code, err.code, err.reason)

import {
  Modulex,
  RateLimitError,
  ValidationError,
  PermissionError,
  ModulexError,
} from 'modulex-js';

const client = new Modulex({
  apiKey: 'mx_live_8Kd2pQ7nR4xWvL0eYbT1',
  organizationId: 'org_9a2f7c41',
});

try {
  const run = await client.executions.run({
    workflowId: 'wf_3f8a21c0',
    input: { topic: 'quarterly report' },
  });
} catch (err) {
  if (err instanceof RateLimitError) {
    // 429 — back off using the parsed Retry-After header.
    console.log('rate limited; retry after', err.retryAfter);
  } else if (err instanceof PermissionError) {
    // 403 — role/scope rejection (Shape A).
    console.log(err.message);
  } else if (err instanceof ValidationError) {
    // 422 — err.body.detail is the loc/msg/type array.
    console.log(err.body);
  } else if (err instanceof ModulexError) {
    // 402 and 410 fall through to the base class here.
    // code / layer / reason are still populated for DenialEnvelope bodies.
    console.log(err.status, err.code, err.layer, err.reason);
  } else {
    throw err;
  }
}