Error handling

Base pattern

import { isInsufficientCreditsError, isMappaError, isStreamError } from "@mappa-ai/mappa-node";

try {
  const receipt = await mappa.reports.createJobFromUrl({
    url: "https://example.com/call.mp3",
    output: { template: "general_report" },
    target: { strategy: "dominant" },
  });
  const report = await receipt.handle?.wait();
  console.info(report?.id);
} catch (err) {
  if (isInsufficientCreditsError(err)) {
    console.error("insufficient credits", err.required, err.available);
    throw err;
  }

  if (isStreamError(err)) {
    console.error("stream failed", err.jobId, err.retryCount);
    throw err;
  }

  if (isMappaError(err)) {
    console.error("mappa error", err.code, err.requestId, err.message);
    throw err;
  }

  throw err;
}

Job terminal errors

import { JobCanceledError, JobFailedError } from "@mappa-ai/mappa-node";

try {
  const report = await mappa.reports.makeHandle("job_123").wait();
  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);
  }
}

Retry guidance

• Retry transient transport/API failures (429/5xx) with backoff.
• Do not auto-retry validation/auth failures (400/401/403/422).
• Always log requestId when available for support/debug tracing.