Error Handling

When you integrate Paragraph CMS into an application, error handling should be explicit, boring, and predictable.

That means two things:

• always branch on failure before you touch returned content; and
• handle API errors differently from transport or runtime failures.

@paragraphcms/client returns { data, error }

The official SDK now uses a non-throwing result shape for every public method:

const { data, error } = await client.page.getBySlug("pricing");

if (error) {
  console.error(error.message);
  return;
}

console.log(data.title);

This is the correct default pattern. Do not assume data exists. Check error first, then continue with the happy path.

Handle ParagraphApiError and ParagraphClientError differently

@paragraphcms/client returns one of two error types:

• ParagraphApiError: the Paragraph API responded, but the request failed;
• ParagraphClientError: the request never completed cleanly because of timeout, abort, or another client-side failure.

That distinction matters because the recovery path is different.

const { data, error } = await client.page.getBySlug(slug);

if (error) {
  if (error.name === "ParagraphApiError") {
    if (error.status === 404) {
      return notFound();
    }

    if (error.status === 429) {
      return new Response("Try again soon.", { status: 503 });
    }
  }

  console.error(error);
  return new Response("Internal Server Error", { status: 500 });
}

return Response.json(data);

Treat common failure modes intentionally

404

This usually means the requested page, locale, or related resource does not exist. Map this cleanly to a not-found response in your framework instead of turning it into a generic server error.

429

This means your integration is too chatty. Reduce direct API traffic, cache aggressively, and avoid repeated page-by-page fetch loops during request time.

Timeouts and aborted requests

These should be treated as operational failures, not content-state failures. Log them, surface a stable fallback response, and investigate the calling path.

Prefer narrow error boundaries

Keep the data/error check close to the SDK call that can fail.

Good:

const pageResult = await client.page.getBySlug(slug);

if (pageResult.error) {
  return handleParagraphError(pageResult.error);
}

return renderPage(pageResult.data);

Less good:

const page = (await client.page.getBySlug(slug)).data;
const related = (await client.pages.list({ collection: "Blog" })).data;

The second version makes it easier to accidentally dereference null or lose the context needed to respond correctly.

Centralize repeated handling

If several routes need the same policy, move it into one helper:

function handleParagraphError(error: Error & { status?: number }) {
  if (error.status === 404) {
    return new Response("Not Found", { status: 404 });
  }

  if (error.status === 429) {
    return new Response("Temporarily Unavailable", { status: 503 });
  }

  console.error(error);
  return new Response("Internal Server Error", { status: 500 });
}

The goal is consistency. Your application should not answer the same SDK failure three different ways depending on which route triggered it.

Keep delivery code simple

The best error handling strategy is still architectural:

• fetch on the server, not in the browser;
• prefer static generation for published content;
• use direct API reads mostly for preview, automation, and internal tools; and
• avoid high-frequency request patterns that create avoidable failure states.

If the integration path is simple, error handling stays simple too.