Error codes

This reference is scoped to external API-key workflows.

HTTP statuses

Status	Meaning
400	bad request
401	missing/invalid API key
403	forbidden
404	resource not found
409	conflict
410	resource gone
422	validation failure
429	rate limited
500	internal error

SDK error classes

Class	Typical trigger
MappaError	base SDK error
ApiError	non-2xx API response
AuthError	401/403 responses
ValidationError	422 responses
RateLimitError	429 responses
InsufficientCreditsError	insufficient_credits response
JobFailedError	async job terminal failure
JobCanceledError	async job canceled
StreamError	SSE stream retries exhausted

Minimal handling pattern

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

try {
  const receipt = await mappa.reports.createJob({
    media: { mediaId: "media_123" },
    output: { template: "general_report" },
    target: { strategy: "dominant" },
  });
  await (receipt.handle ?? mappa.reports.makeHandle(receipt.jobId)).wait();
} catch (err) {
  if (isInsufficientCreditsError(err)) {
    console.error(err.required, err.available);
  } else if (isStreamError(err)) {
    console.error(err.jobId, err.retryCount);
  } else if (isMappaError(err)) {
    console.error(err.code, err.requestId, err.message);
  }
}