Error Handling

The SDK provides typed error classes for different failure scenarios.

Error Hierarchy

All SDK errors extend from QumraError, making it easy to catch and handle specific error types.

QumraError (base)
├── QumraAuthError
├── QumraFetchError
└── QumraValidationError

QumraError (Base)

The base error class for all SDK errors. All other error classes extend from this.

class QumraError extends Error {
  readonly code: string;
  constructor(message: string, code: string);
}

Property	Type	Description
code	string	Machine-readable error code
message	string	Human-readable error description

QumraAuthError

Thrown when authentication fails, such as an invalid or expired token, or missing credentials.

Property	Value
code	"AUTH_ERROR"

Common causes:

• Invalid or expired JWT token
• Missing API credentials
• Revoked access token

QumraFetchError

Thrown when an API request to the Qumra platform fails. Includes the HTTP response details for debugging.

class QumraFetchError extends QumraError {
  readonly status: number;
  readonly statusText: string;
  readonly responseBody: string;
}

Property	Type	Description
code	string	Always "FETCH_ERROR"
status	number	HTTP status code (e.g., 404, 500)
statusText	string	HTTP status text (e.g., "Not Found")
responseBody	string	Raw response body from the API

QumraValidationError

Thrown by request validation utilities such as bot detection and iframe validation.

Property	Value
code	"VALIDATION_ERROR"

Common causes:

• Request detected as a bot (validateNotBot)
• Request not from a valid iframe context (validateIframeRequest)

Complete Error Handling Example

import {
  QumraAuthError,
  QumraFetchError,
  QumraValidationError,
} from "@qumra/app-sdk";
import { authenticate } from "~/qumra.server";

export async function loader({ request }: { request: Request }) {
  try {
    const { admin } = await authenticate.admin(request);
    const data = await admin.graphql(`query { shop { name } }`);
    return Response.json(data);
  } catch (error) {
    if (error instanceof Response) {
      // OAuth redirect - return it as-is
      return error;
    }
    if (error instanceof QumraAuthError) {
      return Response.json({ error: "Authentication failed" }, { status: 401 });
    }
    if (error instanceof QumraFetchError) {
      return Response.json(
        { error: "API request failed", status: error.status },
        { status: 502 }
      );
    }
    if (error instanceof QumraValidationError) {
      return Response.json({ error: "Invalid request" }, { status: 400 });
    }
    throw error;
  }
}

تحذير خطير

Always check for Response type first. During OAuth redirects, authenticate.admin() throws a Response object that must be returned to the client.