Error Handling

The SDK throws four error types. Always check for AbortError first (request cancellation), then NetworkError, then MaintenanceError, then the base HaspSDKError.

Error Types

DOMException (AbortError)

Thrown when a request is cancelled via AbortSignal or sdk.destroy(). This is not a network or server error.

if (error instanceof DOMException && error.name === 'AbortError') {
  return; // cancelled — no action needed
}

NetworkError

Thrown when the fetch() call itself fails — device offline, DNS failure, etc. GET requests are retried automatically before this fires.

if (error instanceof HaspSDK.NetworkError) {
  showMessage('Check your internet connection.');
}

MaintenanceError

Thrown proactively when write operations are attempted while the SDK is in maintenance state.

if (error instanceof HaspSDK.MaintenanceError) {
  showMessage('App is being updated. Try again shortly.');
}

HaspSDKError

The base class for all server-side errors. Check error.code against ErrorCode constants.

if (error instanceof HaspSDK.HaspSDKError) {
  const { ErrorCode } = HaspSDK;

  if (error.code === ErrorCode.ValidationFailed) {
    const fieldErrors = error.getFieldErrors();
    showFieldErrors(fieldErrors);
  } else if (error.code === ErrorCode.NotFound) {
    showMessage('Record not found.');
  } else if (error.code === ErrorCode.InsufficientRole) {
    showMessage('Your role does not allow this.');
  } else if (error.code === ErrorCode.Forbidden) {
    showMessage('You do not have access to this app.');
  } else if (error.code === ErrorCode.RateLimited) {
    showMessage('Too many requests. Try again shortly.');
  } else {
    showMessage('Something went wrong. Please try again.');
  }
}

Complete Pattern

const { ErrorCode, NetworkError, MaintenanceError, HaspSDKError } = HaspSDK;

try {
  await sdk.createRecord('tasks', data);
} catch (error) {
  if (error instanceof DOMException && error.name === 'AbortError') {
    return;
  }
  if (error instanceof NetworkError) {
    showMessage('Check your internet connection.');
  } else if (error instanceof MaintenanceError) {
    showMessage('App is being updated. Try again shortly.');
  } else if (error instanceof HaspSDKError) {
    if (error.code === ErrorCode.ValidationFailed) {
      showFieldErrors(error.getFieldErrors());
    } else {
      showMessage(error.message);
    }
  }
}

ErrorCode Constants

ErrorCode covers the codes an app typically branches on. Codes come from two places:

Set by the SDK itself: MISSING_APP_ID, UNAUTHORIZED, MAINTENANCE, NETWORK_ERROR, and UNKNOWN.
Passed through unchanged from the Data API’s error.code: every other code. The API can return codes with no constant (for example INTERNAL_ERROR or IP_NOT_ALLOWED); error.code is a plain string, so compare those directly.

Constant	Value	Source	When thrown
`ErrorCode.Unauthorized`	`UNAUTHORIZED`	SDK	Any HTTP 401 — not signed in or session expired. The SDK calls `onUnauthorized()` first
`ErrorCode.MissingAppId`	`MISSING_APP_ID`	SDK	Constructor called without `appId` and `window.__HASP__` not set. The API returns the same code for a `/bootstrap` request with no `X-Hasp-AppId`, which the SDK never sends
`ErrorCode.Forbidden`	`FORBIDDEN`	API	The user does not reach this project or app — including `getBootstrap()` for a user with no access to the app — or the app does not accept anonymous submissions (HTTP 403)
`ErrorCode.InsufficientRole`	`INSUFFICIENT_ROLE`	API	The user reaches the project, but their role cannot read, write, or delete records (HTTP 403). `error.details.required_capability` names the missing capability
`ErrorCode.NotFound`	`NOT_FOUND`	API	Record, entity, file, or app not found
`ErrorCode.ValidationFailed`	`VALIDATION_FAILED`	API	The request failed validation (HTTP 422), including an invalid filter, sort, or cursor — check `getFieldErrors()`
`ErrorCode.RateLimited`	`RATE_LIMITED`	API	Too many requests — retried automatically; throws if all retries are exhausted
`ErrorCode.AttachmentTooLarge`	`ATTACHMENT_TOO_LARGE`	API	`uploadFile()`: the file exceeds the plan’s single-attachment limit
`ErrorCode.AttachmentStorageLimitExceeded`	`ATTACHMENT_STORAGE_LIMIT_EXCEEDED`	API	`uploadFile()`: the upload would exceed the org’s attachment storage limit
`ErrorCode.MalwareDetected`	`MALWARE_DETECTED`	API	`uploadFile()`: the file failed malware scanning and was not stored
`ErrorCode.Maintenance`	`MAINTENANCE`	SDK	Any HTTP 503, or a write attempted while the SDK is in maintenance state
`ErrorCode.NetworkError`	`NETWORK_ERROR`	SDK	Network unreachable
`ErrorCode.Unknown`	`UNKNOWN`	SDK	The error response carried no parseable `error.code`, or a success response was not valid JSON

The v1 SDK never removes a constant, so ErrorCode also still carries AccessDenied (ACCESS_DENIED), ReadOnlyRecord, StorageLimitReached, QueryTooComplex, and PreviewMode. They are deprecated and nothing returns them: getBootstrap() now refuses a user with no access with FORBIDDEN, like every other endpoint, so compare against ErrorCode.Forbidden.

Validation Field Errors

When error.code === ErrorCode.ValidationFailed, call error.getFieldErrors() to get a { fieldKey: 'message' } map of the first error per field:

const fieldErrors = error.getFieldErrors();
// { title: 'This field is required.', status: 'Invalid value.' }

Object.entries(fieldErrors).forEach(([field, message]) => {
  const el = document.getElementById(`error-${field}`);
  if (el) el.textContent = message;
});

For bulk operations, keys are prefixed with the item’s position in the batch — records.1.title, updates.0.id, ids.2 — so you can point at the exact row that failed.

401 Handling

On 401, the SDK calls onUnauthorized() (defaults to redirecting to the runtime sign-in page, /auth, and back to the current page afterwards) then throws HaspSDKError with ErrorCode.Unauthorized. Override onUnauthorized in the constructor to save draft state before redirecting.

AI Studio

Platform

AI API

Data API

App Builder SDK

Error Handling

Error Types

DOMException (AbortError)

NetworkError

MaintenanceError

HaspSDKError

Complete Pattern

ErrorCode Constants

Validation Field Errors

401 Handling

​Error Types

​DOMException (AbortError)

​NetworkError

​MaintenanceError

​HaspSDKError

​Complete Pattern

​ErrorCode Constants

​Validation Field Errors

​401 Handling

Error Types

DOMException (AbortError)

NetworkError

MaintenanceError

HaspSDKError

Complete Pattern

ErrorCode Constants

Validation Field Errors

401 Handling