Error handling

Base pattern

import {
  isConduitError,
  isInsufficientCreditsError,
  isRateLimitError,
  isRemoteFetchTimeoutError,
  isStreamError,
} from "@mappa-ai/conduit"

try {
  const receipt = await conduit.reports.create({
    source: { url: "https://example.com/call.mp3" },
    output: { template: "general_report" },
    target: { strategy: "dominant" },
    webhook: { url: "https://your-app.com/webhooks/conduit" },
  })
  console.info(receipt.jobId)
} catch (err) {
  if (isInsufficientCreditsError(err)) {
    console.error(err.required, err.available)
    throw err
  }

  if (isRateLimitError(err)) {
    console.error(err.retryAfterMs)
    throw err
  }

  if (isRemoteFetchTimeoutError(err)) {
    console.error(err.url)
    throw err
  }

  if (isStreamError(err)) {
    console.error(err.jobId, err.retryCount)
    throw err
  }

  if (isConduitError(err)) {
    console.error(err.code, err.requestId, err.message)
    throw err
  }

  throw err
}

Handle terminal errors

import {
  JobCanceledError,
  JobFailedError,
  TimeoutError,
} from "@mappa-ai/conduit"

try {
  const report = await receipt.handle?.wait({ timeoutMs: 10 * 60_000 })
  console.info(report?.id)
} catch (err) {
  if (err instanceof JobFailedError) console.error(err.jobId, err.message)
  if (err instanceof JobCanceledError) console.error(err.jobId, err.message)
  if (err instanceof TimeoutError) console.error(err.code, err.message)
  throw err
}

Retry guidance

• Retry transient failures (429, 5xx) with exponential backoff.
• Do not retry request-shape and auth failures (400, 401, 403, 422).
• Log request ids for support and debugging.