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

Billing and plan codes

HTTP status	Code	Meaning
402	insufficient_credits	Workspace balance cannot cover requested operation.
403	plan_restriction	Operation is not allowed on current plan.
410	gone	Endpoint/resource is removed and no longer available.

Analyze migration snippet

/v1/analyze/* has been removed and now returns 410 with code: "gone".

Use this replacement path:

1. POST /v1/files
2. POST /v1/reports/jobs
3. GET /v1/jobs/:jobId and GET /v1/reports/by-job/:jobId

SDK error classes

Class	Typical trigger
ConduitError	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 {
  Conduit,
  isInsufficientCreditsError,
  isConduitError,
  isStreamError,
} from "@mappa-ai/conduit";

try {
  const conduit = new Conduit({ apiKey: process.env.CONDUIT_API_KEY! })
  const receipt = await conduit.reports.create({
    source: { mediaId: "media_123" },
    output: { template: "general_report" },
    target: { strategy: "dominant" },
    webhook: { url: "https://your-app.com/webhooks/conduit" },
  });
  await receipt.handle?.wait();
} catch (err) {
  if (isInsufficientCreditsError(err)) {
    console.error(err.required, err.available);
  } else if (isStreamError(err)) {
    console.error(err.jobId, err.retryCount);
  } else if (isConduitError(err)) {
    console.error(err.code, err.requestId, err.message);
  }
}