Errors

Every answer that is not 2xx throws a PrismDraftError. It carries the API's error code, which is what your code should branch on.

PrismDraftError

The API answers failures with one shape, { "error": { "code", "message", "details" } }. The SDK turns it into an Error with these fields:

code is typed string, not a union, so a code added to the API later does not break a switch.

An answer that is not this shape, such as a bare 502 from a gateway, is also a PrismDraftError: its status is the HTTP status, code is INTERNAL_ERROR, and message is the status text.

A 2xx answer whose body is not JSON, such as an HTML page from a proxy in front of the API, is a PrismDraftError as well, for any method: status is the HTTP status (200, say), code is INVALID_RESPONSE, and message is The API returned a non-JSON body. The message holds neither the body nor the URL. The SDK does not retry it. An empty 2xx body is not an error.

Codes

Two details:

• 404 is not always "does not exist". A workspace or resource you have no access to answers RESOURCE_NOT_FOUND, the same as one that is not there. FORBIDDEN means you can see it exists but your role may not do this.
• Validation runs before authentication. A request that is malformed answers 400 even when the key is wrong; fix the request first, then the key.

details

For INVALID_REQUEST, details.issues lists what failed. Each issue has a path (a dotted name such as title or translations.0.name) and a message. A Markdown import that cannot be converted lists { construct, line } instead, and an image that cannot be downloaded sets details.src.

For GENERATION_FAILED, the code has two sources. A run that started and failed is recorded on the job (job.errorCode). The same code is also a synchronous 502 answer when the deployment's AI cannot serve the call at all, before any credit is reserved or job created. It comes from generation start, outline approval, translations, category suggestions, planning ideas, publishing plan suggestions (plans.suggest), briefs, links and social posts, AI edit, and image regeneration. These answers carry details.reason, either ai_paused (an administrator paused the capability) or ai_not_configured (no provider or key is set up), and details.capability, one of text, image, embedding or search. Nothing was charged, so there is nothing to refund. The SDK does not retry a 502 from these calls, because it retries only GET requests; fix the deployment's settings, or ask its administrator, and send the request again.

For FORBIDDEN, details.permission names the missing permission, which is the quickest way to find the role you need.

For CONFLICT, details.reason names the cause when the API has one. article_state_changed means the article changed status while a request was moving it (for example it was approved, unpublished or edited by someone else between the API reading it and writing the new status), so nothing was changed; details.from and details.to give the status it was read in and the one asked for. Read the article again and, if the move still applies, send the request again. The SDK does not retry it for you, because it retries only GET requests.

Handle errors by code

import { PrismDraftError } from "@prism-draft/sdk";

type Outcome = "published" | "not approved yet" | "not allowed" | "no such article";

async function tryPublish(): Promise<Outcome> {
  try {
    await pd.articles.publish({ articleId });
    return "published";
  } catch (error) {
    if (!(error instanceof PrismDraftError)) throw error;
    switch (error.code) {
      case "CONFLICT":
        return "not approved yet"; // only an APPROVED article can be published
      case "FORBIDDEN":
        return "not allowed"; // error.details?.permission says which permission is missing
      case "RESOURCE_NOT_FOUND":
        return "no such article";
      default:
        throw error;
    }
  }
}

Tell an unavailable AI apart from a failed run:

import { PrismDraftError } from "@prism-draft/sdk";

try {
  await pd.generation.start({ articleId });
} catch (error) {
  if (error instanceof PrismDraftError && error.code === "GENERATION_FAILED") {
    const reason = error.details?.reason; // "ai_paused" | "ai_not_configured"
    const capability = error.details?.capability; // "text" | "image" | "embedding" | "search"
    console.log(`AI unavailable: ${String(reason)} (${String(capability)})`);
  } else {
    throw error;
  }
}

Read the validation issues of a refused request:

import { PrismDraftError } from "@prism-draft/sdk";

interface Issue {
  path?: string;
  message?: string;
  construct?: string;
  line?: number;
}

function issuesOf(error: PrismDraftError): Issue[] {
  const issues = error.details?.issues;
  return Array.isArray(issues) ? (issues as Issue[]) : [];
}

try {
  await pd.articles.create({ body: { projectId, title: "" } });
} catch (error) {
  if (error instanceof PrismDraftError && error.code === "INVALID_REQUEST") {
    for (const issue of issuesOf(error)) console.log(`${issue.path}: ${issue.message}`);
  } else {
    throw error;
  }
}

Other things a call can throw

A PrismDraftError means the API answered. Other failures are different errors:

import { PrismDraftError, PrismDraftTimeoutError } from "@prism-draft/sdk";

try {
  await pd.articles.get({ articleId }, { timeoutMs: 5_000 });
} catch (error) {
  if (error instanceof PrismDraftTimeoutError) {
    console.log(`no answer within ${error.timeoutMs} ms`);
  } else if (error instanceof PrismDraftError) {
    console.log(error.status, error.code, error.message);
  } else {
    throw error;
  }
}